@veraxhq/verax 0.3.0 → 0.4.0

package/src/verax/observe/snapshot-ops.js

@@ -0,0 +1,94 @@
+/**
+ * SNAPSHOT OPERATIONS MODULE
+ * 
+ * Encapsulates snapshot loading, comparison, building, and saving logic.
+ * Extracted from observe/index.js (STAGE D2.1).
+ * 
+ * Preserves 100% of original behavior:
+ * - Same incremental mode conditions
+ * - Same snapshot JSON shape
+ * - Same load/save timing
+ * - Same trace filtering
+ */
+
+import {
+  loadPreviousSnapshot,
+  buildSnapshot,
+  compareSnapshots,
+  saveSnapshot
+} from '../core/incremental-store.js';
+
+/**
+ * Initialize snapshot operations at the beginning of observation
+ * 
+ * Loads previous snapshot, compares with baseline, determines incremental mode.
+ * Extracted from lines 108-111 of observe/index.js
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {Object} manifest - Loaded manifest object
+ * @returns {Promise<{oldSnapshot: Object|null, snapshotDiff: Object|null, incrementalMode: boolean}>}
+ */
+export async function initializeSnapshot(projectDir, manifest) {
+  let oldSnapshot = null;
+  let snapshotDiff = null;
+  let incrementalMode = false;
+
+  // SCALE INTELLIGENCE: Load previous snapshot for incremental mode
+  oldSnapshot = loadPreviousSnapshot(projectDir);
+  if (oldSnapshot) {
+    const currentSnapshot = buildSnapshot(manifest, []);
+    snapshotDiff = compareSnapshots(oldSnapshot, currentSnapshot);
+    incrementalMode = !snapshotDiff.hasChanges; // Use incremental if nothing changed
+  }
+
+  return {
+    oldSnapshot,
+    snapshotDiff,
+    incrementalMode
+  };
+}
+
+/**
+ * Finalize snapshot operations at the end of observation
+ * 
+ * Builds current snapshot from observed interactions, saves for next run,
+ * and creates incremental metadata for observation object.
+ * Extracted from lines 789-811 of observe/index.js
+ * 
+ * @param {Object} manifest - Loaded manifest object (or null if not provided)
+ * @param {Array} traces - All collected traces
+ * @param {Array} skippedInteractions - Array of skipped interactions
+ * @param {boolean} incrementalMode - Whether incremental mode was enabled
+ * @param {Object} snapshotDiff - Snapshot diff from initialization (or null)
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run identifier
+ * @param {string} url - Initial URL (fallback for trace.before.url)
+ * @returns {Promise<{enabled: boolean, snapshotDiff: Object, skippedInteractionsCount: number}|null>}
+ */
+export async function finalizeSnapshot(manifest, traces, skippedInteractions, incrementalMode, snapshotDiff, projectDir, runId, url) {
+  let incrementalMetadata = null;
+
+  // SCALE INTELLIGENCE: Save snapshot for next incremental run
+  if (manifest) {
+    // Build snapshot from current run (extract interactions from traces)
+    const observedInteractions = traces
+      .filter(t => t.interaction && !t.incremental)
+      .map(t => ({
+        type: t.interaction?.type,
+        selector: t.interaction?.selector,
+        url: t.before?.url || url
+      }));
+
+    const currentSnapshot = buildSnapshot(manifest, observedInteractions);
+    saveSnapshot(projectDir, currentSnapshot, runId);
+
+    // Add incremental mode metadata to observation
+    incrementalMetadata = {
+      enabled: incrementalMode,
+      snapshotDiff: snapshotDiff,
+      skippedInteractionsCount: skippedInteractions.filter(s => s.reason === 'incremental_unchanged').length
+    };
+  }
+
+  return incrementalMetadata;
+}

package/src/verax/observe/ui-signal-sensor.js

@@ -2,30 +2,14 @@
  * WAVE 3: UI Signal Sensor
  * Detects user-visible feedback signals: loading states, dialogs, error messages
  * Conservative: only count signals with accessibility semantics or explicit attributes
- * 
- * CSS SPINNER DETECTION: Detects CSS-only loading indicators without semantic attributes
  */
 
-import {
-  isBorderSpinnerPattern,
-  isRotationAnimation,
-  isPulseAnimation,
-  isSpinnerSize,
-  isDecorativeElement,
-  CSS_SPINNER_REASON_CODES
-} from '../shared/css-spinner-rules.js';
-
 export class UISignalSensor {
   /**
    * Snapshot current UI signals on the page.
-   * Returns: { hasLoadingIndicator, hasDialog, buttonStateChanged, errorSignals, explanation, cssSpinners }
-   * 
-   * @param {Object} page - Playwright page object
-   * @param {number} interactionTime - Optional: timestamp of interaction (for timing window)
-   * @param {Object} beforeSnapshot - Optional: snapshot before interaction (for correlation)
-   * @returns {Promise<Object>} UI signals snapshot
+   * Returns: { hasLoadingIndicator, hasDialog, buttonStateChanged, errorSignals, explanation }
    */
-  async snapshot(page, interactionTime = null, beforeSnapshot = null) {
+  async snapshot(page) {
     const signals = await page.evaluate(() => {
       const result = {
         hasLoadingIndicator: false,
@@ -101,136 +85,6 @@ export class UISignalSensor {
         );
       }
 
-      // CSS SPINNER DETECTION: Detect CSS-only loading indicators
-      result.cssSpinners = [];
-      result.cssSpinnerDetected = false;
-      
-      const allElements = Array.from(document.querySelectorAll('*'));
-      const currentTime = Date.now();
-      const MAX_SPINNER_SIZE = 100;
-      const MIN_SPINNER_SIZE = 8;
-      const SPINNER_TIMING_WINDOW_MS = 2000;
-      
-      // Helper functions (inlined for browser context)
-      const isBorderSpinnerPattern = (style) => {
-        const borderWidth = parseFloat(style.borderWidth) || 0;
-        const borderTopWidth = parseFloat(style.borderTopWidth) || 0;
-        if (borderWidth < 2 && borderTopWidth < 2) return false;
-        
-        const borderColor = style.borderColor || '';
-        const borderTopColor = style.borderTopColor || '';
-        const hasDifferentTopColor = borderTopColor && borderColor && borderTopColor !== borderColor && borderTopColor !== 'rgba(0, 0, 0, 0)';
-        
-        const borderRadius = style.borderRadius || '';
-        const isCircular = borderRadius.includes('50%') || borderRadius.includes('999') || parseFloat(borderRadius) > 20;
-        
-        return hasDifferentTopColor && isCircular;
-      };
-      
-      const isRotationAnimation = (style) => {
-        const animationName = (style.animationName || '').toLowerCase();
-        const animation = (style.animation || '').toLowerCase();
-        const transform = style.transform || '';
-        const animationDuration = style.animationDuration || '';
-        
-        const spinnerKeywords = ['spin', 'rotate', 'loading', 'loader'];
-        const hasSpinnerKeyword = spinnerKeywords.some(k => animationName.includes(k) || animation.includes(k));
-        const hasRotation = transform.includes('rotate');
-        const isAnimated = animationDuration && animationDuration !== '0s' && !animationDuration.includes('none');
-        
-        return (hasRotation || hasSpinnerKeyword) && isAnimated;
-      };
-      
-      const isPulseAnimation = (style) => {
-        const animationName = (style.animationName || '').toLowerCase();
-        const animation = (style.animation || '').toLowerCase();
-        const animationDuration = style.animationDuration || '';
-        const opacity = parseFloat(style.opacity) || 1;
-        
-        const pulseKeywords = ['pulse', 'fade', 'loading'];
-        const hasPulseKeyword = pulseKeywords.some(k => animationName.includes(k) || animation.includes(k));
-        const isAnimated = animationDuration && animationDuration !== '0s' && !animationDuration.includes('none');
-        const hasOpacityVariation = opacity < 1;
-        
-        return hasPulseKeyword && isAnimated && hasOpacityVariation;
-      };
-      
-      const isSpinnerSize = (width, height) => {
-        const maxDim = Math.max(width, height);
-        const minDim = Math.min(width, height);
-        if (maxDim > MAX_SPINNER_SIZE || minDim < MIN_SPINNER_SIZE) return false;
-        const aspectRatio = maxDim / (minDim || 1);
-        return aspectRatio <= 2.0;
-      };
-      
-      for (const el of allElements) {
-        const style = window.getComputedStyle(el);
-        // @ts-expect-error
-        if (el.offsetParent === null || style.visibility === 'hidden' || style.display === 'none' || style.opacity === '0') {
-          continue;
-        }
-        
-        // Skip if element has semantic loading attributes
-        if (el.hasAttribute('aria-busy') || el.hasAttribute('data-loading') || el.getAttribute('role') === 'progressbar') {
-          continue;
-        }
-        
-        const width = el.offsetWidth || 0;
-        const height = el.offsetHeight || 0;
-        const elementId = el.id || `${el.tagName}-${el.className}`;
-        
-        // Check size bounds
-        if (!isSpinnerSize(width, height)) {
-          continue;
-        }
-        
-        // Check for spinner patterns
-        let spinnerType = null;
-        let reasonCode = null;
-        
-        if (isBorderSpinnerPattern(style)) {
-          spinnerType = 'border-spinner';
-          reasonCode = 'UI_CSS_SPINNER_DETECTED_BORDER';
-        } else if (isRotationAnimation(style)) {
-          spinnerType = 'rotation-spinner';
-          reasonCode = 'UI_CSS_SPINNER_DETECTED_ROTATION';
-        } else if (isPulseAnimation(style)) {
-          spinnerType = 'pulse-spinner';
-          reasonCode = 'UI_CSS_SPINNER_DETECTED_PULSE';
-        }
-        
-        if (spinnerType) {
-          result.cssSpinners.push({
-            type: spinnerType,
-            reasonCode,
-            elementId,
-            width,
-            height
-          });
-          result.cssSpinnerDetected = true;
-        }
-      }
-      
-      // Require 2+ independent signals for CONFIRMED CSS spinner feedback
-      if (result.cssSpinnerDetected) {
-        const hasDisabledButton = result.disabledElements.length > 0;
-        const hasPointerEventsDisabled = allElements.some(el => {
-          const style = window.getComputedStyle(el);
-          return style.pointerEvents === 'none';
-        });
-        
-        const corroboratingSignals = [hasDisabledButton, hasPointerEventsDisabled].filter(Boolean).length;
-        
-        if (corroboratingSignals >= 1) {
-          result.hasLoadingIndicator = true;
-          result.explanation.push(`CSS spinner detected with ${corroboratingSignals} corroborating signal(s)`);
-          result.cssSpinnerReasonCode = 'UI_CSS_SPINNER_ACCEPTED_WITH_CORROBORATION';
-        } else {
-          result.explanation.push('CSS spinner detected but no corroborating signals (SUSPECTED)');
-          result.cssSpinnerReasonCode = 'UI_CSS_SPINNER_REJECTED_NO_CORROBORATION';
-        }
-      }
-
       // VALIDATION INTELLIGENCE v1: Detect visible validation feedback
       // Check for aria-invalid="true" with visible error text nearby
       const invalidElements = Array.from(document.querySelectorAll('[aria-invalid="true"]'));

package/src/verax/scan-summary-writer.js

@@ -3,11 +3,8 @@ import { writeFileSync, mkdirSync, readFileSync, existsSync } from 'fs';
 import { computeExpectationsSummary } from './shared/artifact-manager.js';
 import { createImpactSummary } from './core/silence-impact.js';
 import { computeDecisionSnapshot } from './core/decision-snapshot.js';
-import { VERAX_PRODUCT_DEFINITION } from './core/product-definition.js';
-import { ARTIFACT_REGISTRY, getArtifactVersions } from './core/artifacts/registry.js';
-import { generateHumanSummary } from './core/report/human-summary.js';
 
-export async function writeScanSummary(projectDir, url, projectType, learnTruth, observeTruth, detectTruth, manifestPath, tracesPath, findingsPath, runDirOpt, findingsArray = null) {
+export function writeScanSummary(projectDir, url, projectType, learnTruth, observeTruth, detectTruth, manifestPath, tracesPath, findingsPath, runDirOpt, findingsArray = null) {
   if (!runDirOpt) {
     throw new Error('runDirOpt is required');
   }
@@ -18,6 +15,7 @@ export async function writeScanSummary(projectDir, url, projectType, learnTruth,
   let expectationsSummary = { total: 0, navigation: 0, networkActions: 0, stateActions: 0 };
   if (manifestPath && existsSync(manifestPath)) {
     try {
+  // @ts-expect-error - readFileSync with encoding returns string
       const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
       expectationsSummary = computeExpectationsSummary(manifest);
     } catch (error) {
@@ -32,30 +30,21 @@ export async function writeScanSummary(projectDir, url, projectType, learnTruth,
   }
   
   // PHASE 6: Compute determinism summary from decisions.json
-  // PHASE 21.2: Use HARD verdict from determinism contract
   let determinismSummary = null;
   if (runDirOpt && observeTruth?.runId) {
     const decisionsPath = resolve(runDirOpt, 'decisions.json');
     if (existsSync(decisionsPath)) {
       try {
+  // @ts-expect-error - readFileSync with encoding returns string
         const decisions = JSON.parse(readFileSync(decisionsPath, 'utf-8'));
-        const { DecisionRecorder } = await import('./core/determinism-model.js');
+        const { DecisionRecorder } = require('./core/determinism-model.js');
         const recorder = DecisionRecorder.fromExport(decisions);
         const summary = recorder.getSummary();
         
-        // PHASE 21.2: Compute HARD verdict from adaptive events
-        const { computeDeterminismVerdict } = await import('./core/determinism/contract.js');
-        const verdict = computeDeterminismVerdict(recorder);
-        
         determinismSummary = {
-          verdict: verdict.verdict, // PHASE 21.2: HARD verdict (DETERMINISTIC or NON_DETERMINISTIC)
-          message: verdict.message,
-          reasons: verdict.reasons,
-          adaptiveEventsCount: verdict.adaptiveEvents.length,
-          // Legacy fields for backward compatibility
-          isDeterministic: verdict.verdict === 'DETERMINISTIC',
-          totalDecisions: summary.total,
-          decisionsByCategory: summary.byCategory,
+          isDeterministic: summary.isDeterministic,
+          totalDecisions: summary.totalDecisions,
+          decisionsByCategory: summary.decisionsByCategory,
           decisionsPath: decisionsPath
         };
       } catch (error) {
@@ -71,37 +60,19 @@ export async function writeScanSummary(projectDir, url, projectType, learnTruth,
     decisionSnapshot = computeDecisionSnapshot(findingsArray, detectTruth, observeTruth, silences);
   }
   
-  // PHASE 21.10: Generate human summary
-  let humanSummary = null;
-  if (observeTruth?.runId) {
-    try {
-      humanSummary = await generateHumanSummary(projectDir, observeTruth.runId);
-    } catch {
-      // Ignore errors generating human summary
-    }
-  }
-  
   const summary = {
     version: 1,
-    contractVersion: 1,  // PHASE 0: Track schema changes
     scannedAt: new Date().toISOString(),
     url: url,
     projectType: projectType,
     expectationsSummary: expectationsSummary,
-    // PHASE 0: Include Evidence Law statement
-    evidenceLaw: {
-      statement: VERAX_PRODUCT_DEFINITION.evidenceLaw.statement,
-      description: VERAX_PRODUCT_DEFINITION.evidenceLaw.definition,
-      enforcement: VERAX_PRODUCT_DEFINITION.evidenceLaw.enforcement
-    },
     // PHASE 7: Decision snapshot first (most important for human decision-making)
     decisionSnapshot: decisionSnapshot,
     // PHASE 7: Misinterpretation guards (explicit warnings)
     interpretationGuards: {
       zeroFindings: 'Zero findings does NOT mean no problems. Check unverified count and confidence level.',
       deterministicRun: 'Deterministic run does NOT mean correct site. Only means scan was reproducible.',
-      highSilenceImpact: 'High silence impact does NOT mean failures exist. Only means unknowns affect confidence.',
-      evidenceLaw: 'Not all findings are CONFIRMED. Some may be SUSPECTED (insufficient evidence). Only CONFIRMED findings are actionable.'
+      highSilenceImpact: 'High silence impact does NOT mean failures exist. Only means unknowns affect confidence.'
     },
     truth: {
       learn: learnTruth,
@@ -119,17 +90,14 @@ export async function writeScanSummary(projectDir, url, projectType, learnTruth,
     } : null,
     // PHASE 6: Add determinism summary
     determinism: determinismSummary,
-    // PHASE 21.10: Add human summary
-    humanSummary: humanSummary,
     paths: {
       manifest: manifestPath,
       traces: tracesPath,
       findings: findingsPath
-    },
-    artifactVersions: getArtifactVersions()
+    }
   };
   
-  const summaryPath = resolve(scanDir, ARTIFACT_REGISTRY.scanSummary.filename);
+  const summaryPath = resolve(scanDir, 'scan-summary.json');
   writeFileSync(summaryPath, JSON.stringify(summary, null, 2) + '\n');
   
   return {

package/src/verax/shared/artifact-manager.js

@@ -14,15 +14,34 @@
 
 import { existsSync, mkdirSync, writeFileSync, appendFileSync } from 'fs';
 import { resolve } from 'path';
-import { randomBytes } from 'crypto';
-import { buildRunArtifactPaths } from '../core/artifacts/registry.js';
+import { generateRunId as generateDeterministicRunId } from '../core/run-id.js';
+
+const ZERO_BUDGET = Object.freeze({
+  maxScanDurationMs: 0,
+  maxInteractionsPerPage: 0,
+  maxUniqueUrls: 0,
+  interactionTimeoutMs: 0,
+  navigationTimeoutMs: 0,
+});
 
 /**
  * Generate a unique run ID.
  * @returns {string} - 8-character hex ID
  */
-export function generateRunId() {
-  return randomBytes(4).toString('hex');
+export function generateRunId(seed = 'about:blank') {
+  let baseOrigin = 'about:blank';
+  try {
+    baseOrigin = new URL(seed).origin;
+  } catch {
+    baseOrigin = seed;
+  }
+  return generateDeterministicRunId({
+    url: seed,
+    safetyFlags: {},
+    baseOrigin,
+    scanBudget: ZERO_BUDGET,
+    manifestPath: null,
+  });
 }
 
 /**
@@ -31,22 +50,20 @@ export function generateRunId() {
  * @param {string} runId - Run identifier
  * @returns {Object} - Paths to each artifact location
  */
-export function initArtifactPaths(projectRoot, runId = null) {
-  const id = runId || generateRunId();
+export function initArtifactPaths(projectRoot, runId = null, seed = projectRoot) {
+  const id = runId || generateRunId(seed);
   const runDir = resolve(projectRoot, '.verax', 'runs', id);
-  const registryPaths = buildRunArtifactPaths(runDir);
 
   const paths = {
     runId: id,
     runDir,
-    summary: registryPaths.summaryJson,
-    findings: registryPaths.findingsJson,
+    summary: resolve(runDir, 'summary.json'),
+    findings: resolve(runDir, 'findings.json'),
     expectations: resolve(runDir, 'expectations.json'),
-    traces: registryPaths.tracesJsonl,
-    evidence: registryPaths.evidenceDir,
+    traces: resolve(runDir, 'traces.jsonl'),
+    evidence: resolve(runDir, 'evidence'),
     flows: resolve(runDir, 'flows'),
-    artifacts: resolve(projectRoot, '.verax', 'artifacts'), // Legacy compat
-    registry: registryPaths.artifactVersions
+    artifacts: resolve(projectRoot, '.verax', 'artifacts') // Legacy compat
   };
 
   // Create directories

package/src/verax/shared/caching.js

@@ -50,6 +50,7 @@ export function computeCacheKey(projectRoot, tsconfigPath, sourceFiles = []) {
     }
   }
 
+  // @ts-expect-error - digest returns string
   return hash.digest('hex').substring(0, 16); // Use first 16 chars for brevity
 }
 

package/src/verax/shared/expectation-tracker.js

@@ -26,6 +26,7 @@ export function generateExpectationId(expectation, type) {
   
   // Generate stable 8-character hex hash
   const hash = createHash('sha256').update(hashInput).digest('hex');
+  // @ts-expect-error - digest returns string
   return hash.substring(0, 8);
 }
 

package/src/verax/shared/zip-artifacts.js

@@ -45,6 +45,7 @@ export async function createArtifactsZip(runDir, outputPath = null) {
     
     // Handle errors
     archive.on('error', (err) => {
+      output.destroy();
       reject(err);
     });
     
@@ -52,6 +53,11 @@ export async function createArtifactsZip(runDir, outputPath = null) {
       resolvePromise(outputPath);
     });
     
+    output.on('error', (err) => {
+      archive.destroy();
+      reject(err);
+    });
+    
     // Pipe archive data to file
     archive.pipe(output);