@odavl/guardian 0.1.0-rc1 → 0.2.0

package/src/guardian/smoke.js

@@ -0,0 +1,258 @@
+const { AttemptEngine } = require('./attempt-engine');
+const { getAttemptDefinition } = require('./attempt-registry');
+const { BrowserPool } = require('./browser-pool');
+const { checkPrerequisites } = require('./prerequisite-checker');
+const { validateParallel, executeParallel } = require('./parallel-executor');
+const { getTimeoutProfile } = require('./timeout-profiles');
+const { isCiMode } = require('./ci-mode');
+
+const SMOKE_ATTEMPTS = ['universal_reality', 'login', 'signup', 'contact_form'];
+const DEFAULT_PARALLEL = 2;
+const DEFAULT_BUDGET_MS = 30000;
+const DEFAULT_PREREQ_TIMEOUT = 2000;
+const SMOKE_BROWSER_ARGS = ['--no-sandbox', '--disable-setuid-sandbox', '--proxy-bypass-list=*'];
+
+function validateUrl(url) {
+  try {
+    // eslint-disable-next-line no-new
+    new URL(url);
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+function summarizeResults(results) {
+  const success = results.filter(r => r.outcome === 'SUCCESS').length;
+  const friction = results.filter(r => r.outcome === 'FRICTION').length;
+  const failure = results.filter(r => r.outcome === 'FAILURE').length;
+  const skipped = results.filter(r => r.outcome === 'SKIPPED').length;
+  return { success, friction, failure, skipped };
+}
+
+function authPathStatus(results) {
+  const authResults = results.filter(r => r.attemptId === 'login' || r.attemptId === 'signup');
+  const hasAuthSuccess = authResults.some(r => r.outcome === 'SUCCESS' || r.outcome === 'FRICTION');
+  const authFailures = authResults.filter(r => r.outcome === 'FAILURE').length;
+  return { hasAuthSuccess, authFailures };
+}
+
+function chooseExitCode({ failure, friction }, timedOut, authMissing, authFailuresToIgnore = 0) {
+  const effectiveFailures = Math.max(0, failure - authFailuresToIgnore);
+  if (timedOut || authMissing || effectiveFailures > 0) return 2;
+  if (friction > 0) return 1;
+  return 0;
+}
+
+async function executeSmoke(config) {
+  const baseUrl = config.baseUrl;
+  if (!validateUrl(baseUrl)) {
+    throw new Error(`Invalid URL: ${baseUrl}`);
+  }
+
+  const savedNoProxy = { NO_PROXY: process.env.NO_PROXY, no_proxy: process.env.no_proxy };
+  const forcedNoProxy = (process.env.NO_PROXY || process.env.no_proxy)
+    ? `${process.env.NO_PROXY || process.env.no_proxy},127.0.0.1,localhost`
+    : '127.0.0.1,localhost';
+  process.env.NO_PROXY = forcedNoProxy;
+  process.env.no_proxy = forcedNoProxy;
+
+  const ciMode = isCiMode();
+  const timeoutProfile = getTimeoutProfile('fast');
+  const resolvedTimeout = timeoutProfile.default;
+  const budgetMs = Number(process.env.GUARDIAN_SMOKE_BUDGET_MS || config.timeBudgetMs || DEFAULT_BUDGET_MS);
+
+  const parallelValidation = validateParallel(DEFAULT_PARALLEL);
+  if (!parallelValidation.valid) {
+    throw new Error(parallelValidation.error || 'Invalid parallel value');
+  }
+  const parallel = parallelValidation.parallel || DEFAULT_PARALLEL;
+
+  if (!ciMode) {
+    console.log('\nSMOKE MODE: ON');
+    console.log(`Target: ${baseUrl}`);
+    console.log(`Attempts: ${SMOKE_ATTEMPTS.join(', ')}`);
+  } else {
+    console.log('SMOKE MODE: ON');
+    console.log(`Target: ${baseUrl}`);
+    console.log(`Attempts: ${SMOKE_ATTEMPTS.join(', ')}`);
+  }
+
+  const browserPool = new BrowserPool();
+  await browserPool.launch({ headless: !config.headful, timeout: resolvedTimeout, args: SMOKE_BROWSER_ARGS });
+
+  const startedAt = Date.now();
+  let timedOut = false;
+  let shouldStop = false;
+  const attemptResults = [];
+
+  const budgetTimer = setTimeout(() => {
+    timedOut = true;
+    shouldStop = true;
+  }, budgetMs);
+
+  const attemptRunner = async (attemptId) => {
+    if (timedOut) {
+      return null;
+    }
+
+    const attemptDef = getAttemptDefinition(attemptId);
+    if (!attemptDef) {
+      return {
+        attemptId,
+        attemptName: attemptId,
+        outcome: 'FAILURE',
+        error: `Attempt ${attemptId} not found`,
+        friction: null
+      };
+    }
+
+    let context = null;
+    let page = null;
+    let result;
+
+    try {
+      const ctx = await browserPool.createContext({
+        timeout: resolvedTimeout,
+        ignoreHTTPSErrors: true
+      });
+      context = ctx.context;
+      page = ctx.page;
+      await page.goto(baseUrl, { waitUntil: 'domcontentloaded', timeout: resolvedTimeout });
+      const prereq = await checkPrerequisites(page, attemptId, DEFAULT_PREREQ_TIMEOUT);
+      if (!prereq.canProceed) {
+        result = {
+          attemptId,
+          attemptName: attemptDef.name,
+          outcome: 'SKIPPED',
+          skipReason: prereq.reason,
+          friction: null,
+          error: null
+        };
+      } else {
+        const engine = new AttemptEngine({
+          attemptId,
+          timeout: resolvedTimeout,
+          frictionThresholds: {
+            totalDurationMs: 5000,
+            stepDurationMs: 2500,
+            retryCount: 0
+          },
+          maxStepRetries: 1
+        });
+
+        const attemptResult = await engine.executeAttempt(page, attemptId, baseUrl, null, attemptDef.validators || []);
+        result = {
+          attemptId,
+          attemptName: attemptDef.name,
+          outcome: attemptResult.outcome,
+          friction: attemptResult.friction,
+          error: attemptResult.error,
+          successReason: attemptResult.successReason,
+          skipReason: null
+        };
+      }
+    } catch (err) {
+      result = {
+        attemptId,
+        attemptName: attemptDef?.name || attemptId,
+        outcome: 'FAILURE',
+        friction: null,
+        error: err.message,
+        skipReason: null
+      };
+    } finally {
+      if (context) {
+        await browserPool.closeContext(context);
+      }
+    }
+
+    // Enforce fail-fast
+    if (result.outcome === 'FAILURE') {
+      shouldStop = true;
+    }
+
+    // Enforce budget after attempt completes
+    if (Date.now() - startedAt >= budgetMs) {
+      timedOut = true;
+      shouldStop = true;
+    }
+
+    return result;
+  };
+
+  const parallelResults = await executeParallel(
+    SMOKE_ATTEMPTS,
+    attemptRunner,
+    parallel,
+    { shouldStop: () => shouldStop }
+  );
+
+  clearTimeout(budgetTimer);
+  for (const r of parallelResults) {
+    if (r) {
+      attemptResults.push(r);
+    }
+  }
+
+  if (process.env.GUARDIAN_SMOKE_DEBUG) {
+    console.log('DEBUG attempt results:', JSON.stringify(attemptResults, null, 2));
+  }
+
+  const summary = summarizeResults(attemptResults);
+  const authStatus = authPathStatus(attemptResults);
+  const effectiveFailures = Math.max(0, summary.failure - (authStatus.hasAuthSuccess ? authStatus.authFailures : 0));
+  const exitCode = chooseExitCode({ ...summary, failure: effectiveFailures }, timedOut, !authStatus.hasAuthSuccess, 0);
+
+  const elapsed = Date.now() - startedAt;
+
+  const lines = [];
+  lines.push(`Summary: success=${summary.success}, friction=${summary.friction}, failure=${effectiveFailures}, skipped=${summary.skipped}`);
+  if (timedOut) {
+    lines.push(`Result: FAILURE (time budget exceeded at ${elapsed}ms)`);
+  } else if (!authStatus.hasAuthSuccess) {
+    lines.push('Result: FAILURE (auth path unreachable)');
+  } else if (exitCode === 2) {
+    lines.push('Result: FAILURE');
+  } else if (exitCode === 1) {
+    lines.push('Result: FRICTION');
+  } else {
+    lines.push('Result: PASS');
+  }
+
+  for (const line of lines) {
+    console.log(line);
+  }
+
+  await browserPool.close();
+
+  // Restore proxy env vars
+  if (savedNoProxy.NO_PROXY !== undefined) {
+    process.env.NO_PROXY = savedNoProxy.NO_PROXY;
+  } else {
+    delete process.env.NO_PROXY;
+  }
+  if (savedNoProxy.no_proxy !== undefined) {
+    process.env.no_proxy = savedNoProxy.no_proxy;
+  } else {
+    delete process.env.no_proxy;
+  }
+
+  return { exitCode, attemptResults, timedOut, authAvailable: authStatus.hasAuthSuccess, elapsed };
+}
+
+async function runSmokeCLI(config) {
+  try {
+    const result = await executeSmoke(config);
+    process.exit(result.exitCode);
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(2);
+  }
+}
+
+module.exports = {
+  executeSmoke,
+  runSmokeCLI,
+  SMOKE_ATTEMPTS
+};

package/src/guardian/snapshot.js

@@ -38,6 +38,22 @@ class SnapshotBuilder {
    * Add attempt result to snapshot
    */
   addAttempt(attemptResult, artifactDir) {
+    // Phase 7.4: Handle SKIPPED attempts (don't add as signal)
+    if (attemptResult.outcome === 'SKIPPED') {
+      this.snapshot.attempts.push({
+        attemptId: attemptResult.attemptId,
+        attemptName: attemptResult.attemptName,
+        goal: attemptResult.goal,
+        outcome: 'SKIPPED',
+        skipReason: attemptResult.skipReason || 'Prerequisites not met',
+        totalDurationMs: 0,
+        stepCount: 0,
+        failedStepIndex: -1,
+        friction: null
+      });
+      return; // Don't create signals for skipped attempts
+    }
+
     const signal = {
       id: `attempt_${attemptResult.attemptId}`,
       severity: attemptResult.outcome === 'FAILURE' ? 'high' : 'medium',
@@ -123,7 +139,13 @@ class SnapshotBuilder {
       stepsTotal: flowResult.stepsTotal || 0,
       durationMs: flowResult.durationMs || 0,
       failedStep: flowResult.failedStep || null,
-      error: flowResult.error || null
+      error: flowResult.error || null,
+      successEval: flowResult.successEval ? {
+        status: flowResult.successEval.status,
+        confidence: flowResult.successEval.confidence,
+        reasons: (flowResult.successEval.reasons || []).slice(0, 3),
+        evidence: flowResult.successEval.evidence || {}
+      } : null
     });
 
     if (runDir) {

package/src/guardian/success-evaluator.js

@@ -0,0 +1,214 @@
+/**
+ * Wave 1.3 — Outcome-Based Success Evaluator
+ * Deterministic success evaluation for form submissions and key flows.
+ * No reliance on specific confirmation text; uses signals: Network, Navigation, DOM, Errors.
+ */
+
+const URL_SAFE_STATUSES = new Set([200, 201, 202, 204, 302, 303]);
+
+/**
+ * Capture pre-submit state around a submit element's owning form.
+ * @param {import('playwright').Page} page
+ * @param {import('playwright').ElementHandle|null} submitHandle
+ */
+async function captureBeforeState(page, submitHandle) {
+  const url = page.url();
+  const state = await page.evaluate((submitEl) => {
+    const result = {
+      formSelector: null,
+      formExists: false,
+      inputsFilledCount: 0,
+      inputsTotal: 0,
+      ariaInvalidCount: 0,
+      hasAlertRegion: false,
+      alertTextLength: 0,
+      liveRegionTextLength: 0,
+    };
+
+    let form = null;
+    if (submitEl) {
+      form = submitEl.closest('form');
+    } else {
+      form = document.querySelector('form');
+    }
+
+    if (form) {
+      result.formSelector = form.getAttribute('id') ? `#${form.id}` : null;
+      result.formExists = true;
+      const inputs = Array.from(form.querySelectorAll('input, textarea, select'));
+      result.inputsTotal = inputs.length;
+      result.inputsFilledCount = inputs.filter((el) => {
+        const val = (el.value || '').trim();
+        return val.length > 0;
+      }).length;
+      result.ariaInvalidCount = inputs.filter((el) => el.getAttribute('aria-invalid') === 'true').length;
+    }
+
+    // role=alert or [aria-live]
+    const alertEl = document.querySelector('[role="alert"], .alert, .error, .invalid');
+    if (alertEl) {
+      result.hasAlertRegion = true;
+      result.alertTextLength = (alertEl.textContent || '').trim().length;
+    }
+    const liveEl = document.querySelector('[aria-live]');
+    if (liveEl) {
+      result.liveRegionTextLength = (liveEl.textContent || '').trim().length;
+    }
+    return result;
+  }, submitHandle);
+
+  return { url, state };
+}
+
+/**
+ * Capture post-submit state.
+ * @param {import('playwright').Page} page
+ * @param {string|null} originalFormSelector
+ */
+async function captureAfterState(page, originalFormSelector) {
+  const url = page.url();
+  const state = await page.evaluate((formSelector) => {
+    const result = {
+      formExists: false,
+      formDisabled: false,
+      inputsFilledCount: 0,
+      inputsTotal: 0,
+      ariaInvalidCount: 0,
+      hasAlertRegion: false,
+      alertTextLength: 0,
+      liveRegionTextLength: 0,
+    };
+
+    let form = null;
+    if (formSelector) {
+      form = document.querySelector(formSelector);
+    }
+    if (!form) {
+      form = document.querySelector('form');
+    }
+
+    if (form) {
+      result.formExists = true;
+      result.formDisabled = !!form.getAttribute('disabled') || (form.classList.contains('disabled'));
+      const inputs = Array.from(form.querySelectorAll('input, textarea, select'));
+      result.inputsTotal = inputs.length;
+      result.inputsFilledCount = inputs.filter((el) => (el.value || '').trim().length > 0).length;
+      result.ariaInvalidCount = inputs.filter((el) => el.getAttribute('aria-invalid') === 'true').length;
+    }
+
+    const alertEl = document.querySelector('[role="alert"], .alert, .error, .invalid');
+    if (alertEl) {
+      result.hasAlertRegion = true;
+      result.alertTextLength = (alertEl.textContent || '').trim().length;
+    }
+    const liveEl = document.querySelector('[aria-live]');
+    if (liveEl) {
+      result.liveRegionTextLength = (liveEl.textContent || '').trim().length;
+    }
+    return result;
+  }, originalFormSelector);
+
+  return { url, state };
+}
+
+/**
+ * Evaluate success based on signals.
+ * @param {{url:string,state:Object}} before
+ * @param {{url:string,state:Object}} after
+ * @param {{requests:Array,responses:Array,consoleErrors:Array,navChanged:boolean,baseOrigin:string}} events
+ * @returns {{status:'success'|'friction'|'failure',confidence:'high'|'medium'|'low',reasons:string[],evidence:Object}}
+ */
+function evaluateSuccess(before, after, events) {
+  const reasons = [];
+  const evidence = {
+    network: [],
+    urlChanged: before.url !== after.url,
+    formCleared: false,
+    formDisappeared: false,
+    formDisabled: false,
+    alertRegionDelta: 0,
+    liveRegionDelta: 0,
+    ariaInvalidDelta: 0,
+    consoleErrors: events.consoleErrors || [],
+  };
+
+  // A) Network success
+  const baseOrigin = events.baseOrigin;
+  let strongNetworkPositive = false;
+  for (const r of (events.responses || [])) {
+    const req = typeof r.request === 'function' ? r.request() : r.request;
+    if (!req || typeof req.url !== 'function') continue;
+    const url = req.url();
+    const originOk = safeSameOrAllowedOrigin(url, baseOrigin);
+    const method = (typeof req.method === 'function' ? req.method() : '').toUpperCase();
+    const status = typeof r.status === 'function' ? r.status() : r.status;
+    const statusOk = URL_SAFE_STATUSES.has(status);
+    evidence.network.push({ method, url, status, originOk, statusOk });
+    if (originOk && (method === 'POST' || method === 'PUT') && statusOk) {
+      strongNetworkPositive = true;
+    }
+  }
+
+  if (strongNetworkPositive) {
+    reasons.push('Network submit succeeded (safe status and origin)');
+  }
+
+  // B) Navigation
+  const navPositive = !!events.navChanged;
+  if (navPositive) reasons.push('URL changed after submit');
+
+  // C) DOM outcome
+  const beforeState = before.state;
+  const afterState = after.state;
+  evidence.formDisappeared = !!beforeState.formExists && !afterState.formExists;
+  evidence.formDisabled = !!afterState.formDisabled;
+  evidence.formCleared = beforeState.inputsFilledCount > 0 && afterState.inputsFilledCount < beforeState.inputsFilledCount;
+  evidence.alertRegionDelta = (afterState.alertTextLength || 0) - (beforeState.alertTextLength || 0);
+  evidence.liveRegionDelta = (afterState.liveRegionTextLength || 0) - (beforeState.liveRegionTextLength || 0);
+  evidence.ariaInvalidDelta = (afterState.ariaInvalidCount || 0) - (beforeState.ariaInvalidCount || 0);
+
+  const domPositive = evidence.formDisappeared || evidence.formDisabled || evidence.formCleared || evidence.liveRegionDelta > 0;
+  if (domPositive) reasons.push('Form outcome indicates completion (cleared/disabled/disappeared or live region updated)');
+
+  // D) Error outcome
+  const strongNegative = evidence.ariaInvalidDelta > 0 || (afterState.hasAlertRegion && evidence.alertRegionDelta > 0);
+  if (strongNegative) reasons.push('Error markers increased after submit');
+
+  // E) Console errors
+  const consoleNegative = (events.consoleErrors || []).length > 0;
+  if (consoleNegative) reasons.push('Console errors after submit');
+
+  // Decision table
+  let status = 'failure';
+  let confidence = 'low';
+  if (strongNetworkPositive && (navPositive || domPositive) && !strongNegative && !consoleNegative) {
+    status = 'success';
+    confidence = 'high';
+  } else if ((strongNetworkPositive || navPositive || domPositive) && (strongNegative || consoleNegative)) {
+    status = 'friction';
+    confidence = strongNetworkPositive ? 'medium' : 'low';
+  } else if (strongNetworkPositive || navPositive || domPositive) {
+    status = 'success';
+    confidence = 'medium';
+  } else {
+    status = 'failure';
+    confidence = strongNegative ? 'medium' : 'low';
+  }
+
+  return { status, confidence, reasons, evidence };
+}
+
+function safeSameOrAllowedOrigin(url, baseOrigin) {
+  try {
+    const u = new URL(url);
+    return u.origin === baseOrigin;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  captureBeforeState,
+  captureAfterState,
+  evaluateSuccess,
+};

package/src/guardian/timeout-profiles.js

@@ -0,0 +1,57 @@
+/**
+ * Guardian Timeout Profiles
+ * Defines deterministic timeout values for different performance modes
+ */
+
+const TIMEOUT_PROFILES = {
+  fast: {
+    // Fast mode: aggressive timeouts for quick feedback
+    pageLoad: 8000,        // page navigation
+    elementWait: 3000,     // finding elements
+    actionWait: 2000,      // click/type settlement (used by wait-for-outcome)
+    submitSettle: 2500,    // form submission settlement
+    networkWait: 1500,     // network response wait
+    default: 8000
+  },
+  default: {
+    // Default mode: current behavior (balanced)
+    pageLoad: 20000,
+    elementWait: 5000,
+    actionWait: 3500,      // matches DEFAULT_MAX_WAIT in wait-for-outcome
+    submitSettle: 4000,
+    networkWait: 3500,
+    default: 20000
+  },
+  slow: {
+    // Slow mode: patient timeouts for flaky networks
+    pageLoad: 30000,
+    elementWait: 10000,
+    actionWait: 5000,
+    submitSettle: 6000,
+    networkWait: 5000,
+    default: 30000
+  }
+};
+
+function getTimeoutProfile(profileName = 'default') {
+  const profile = TIMEOUT_PROFILES[profileName];
+  if (!profile) {
+    throw new Error(`Invalid timeout profile: ${profileName}. Valid values: ${Object.keys(TIMEOUT_PROFILES).join(', ')}`);
+  }
+  return profile;
+}
+
+function resolveTimeout(configValue, profile) {
+  // If config explicitly sets a timeout, use it (allows override)
+  if (configValue && typeof configValue === 'number') {
+    return configValue;
+  }
+  // Otherwise use profile default
+  return profile.default;
+}
+
+module.exports = {
+  TIMEOUT_PROFILES,
+  getTimeoutProfile,
+  resolveTimeout
+};

package/src/guardian/wait-for-outcome.js

@@ -0,0 +1,120 @@
+/**
+ * Signal-based wait helper for actions.
+ * Prefers navigation/network/DOM quiet signals; falls back to bounded timeout.
+ */
+
+const DEFAULT_MAX_WAIT = 3500; // bounded cap
+const QUIET_WINDOW_MS = 300; // DOM must be quiet for this window
+
+async function waitForOutcome(page, options = {}) {
+  const {
+    actionType = 'click',
+    baseOrigin = null,
+    initialUrl = null,
+    expectNavigation = false,
+    includeUrlChange = true,
+    maxWait = DEFAULT_MAX_WAIT,
+  } = options;
+
+  let resolved = false;
+  const cleanupFns = [];
+
+  const resolveWith = (reason, details = {}) => {
+    if (resolved) return;
+    resolved = true;
+    cleanupFns.forEach((fn) => {
+      try { fn(); } catch {}
+    });
+    return { reason, details };
+  };
+
+  const tasks = [];
+  const start = Date.now();
+
+  // Navigation signal
+  if (expectNavigation) {
+    const navPromise = page.waitForNavigation({ timeout: maxWait }).then(() => resolveWith('navigation')).catch(() => {});
+    tasks.push(navPromise);
+  }
+
+  // URL change signal (even without full nav event)
+  if (expectNavigation && includeUrlChange && initialUrl) {
+    const urlPromise = page.waitForURL((u) => u !== initialUrl, { timeout: maxWait }).then(() => resolveWith('url-change')).catch(() => {});
+    tasks.push(urlPromise);
+  }
+
+  // Network signal: watch for POST/PUT same-origin
+  const networkPromise = new Promise((res) => {
+    const handler = (response) => {
+      try {
+        const req = response.request();
+        const method = (req.method() || '').toUpperCase();
+        const url = req.url();
+        const status = response.status();
+        const originOk = baseOrigin ? new URL(url).origin === baseOrigin : true;
+        if ((method === 'POST' || method === 'PUT') && originOk) {
+          const out = resolveWith('network', { method, status, url });
+          if (out) res(out);
+        }
+      } catch {}
+    };
+    page.on('response', handler);
+    cleanupFns.push(() => page.off('response', handler));
+  });
+  tasks.push(networkPromise);
+
+  // DOM quiet signal via MutationObserver
+  const domPromise = new Promise((res) => {
+    let lastMutation = Date.now();
+    let hasMutated = false;
+    const quietCheck = () => {
+      if (!hasMutated) return;
+      if (Date.now() - lastMutation >= QUIET_WINDOW_MS) {
+        const out = resolveWith('dom-quiet');
+        if (out) res(out);
+      }
+    };
+    const interval = setInterval(quietCheck, 80);
+    cleanupFns.push(() => clearInterval(interval));
+    page.evaluate(() => {
+      window.__guardianLastMutation = Date.now();
+      window.__guardianHasMutated = false;
+      if (window.__guardianDomObserver) {
+        try { window.__guardianDomObserver.disconnect(); } catch (e) {}
+      }
+      const obs = new MutationObserver(() => {
+        window.__guardianLastMutation = Date.now();
+        window.__guardianHasMutated = true;
+      });
+      obs.observe(document.documentElement || document.body, { childList: true, subtree: true, attributes: true, characterData: true });
+      window.__guardianDomObserver = obs;
+    }).catch(() => {});
+    const pollMutation = setInterval(async () => {
+      try {
+        const data = await page.evaluate(() => ({
+          last: window.__guardianLastMutation || Date.now(),
+          mutated: !!window.__guardianHasMutated
+        }));
+        lastMutation = data.last;
+        if (data.mutated) hasMutated = true;
+      } catch {}
+    }, 120);
+    cleanupFns.push(() => clearInterval(pollMutation));
+  });
+  tasks.push(domPromise);
+
+  // Bounded fallback
+  const timeoutPromise = new Promise((res) => {
+    const t = setTimeout(() => {
+      const out = resolveWith('timeout', { elapsedMs: Date.now() - start });
+      if (out) res(out);
+    }, maxWait);
+    cleanupFns.push(() => clearTimeout(t));
+  });
+  tasks.push(timeoutPromise);
+
+  const first = await Promise.race(tasks);
+  return first || { reason: 'timeout', details: { elapsedMs: maxWait } };
+}
+
+module.exports = { waitForOutcome };