@hyperfixi/testing-framework 2.5.0 → 2.6.0

package/dist/{assertions-CthVynH6.d.mts → assertions-CsGP61iW.d.mts}

@@ -455,4 +455,4 @@ declare function createExpectAPI(): ExpectAPI;
  */
 declare function createAssertAPI(): AssertAPI;
 
-export { type AccessibilityCheckResult as A, type BrowserTestOptions as B, type CoverageData as C, createAssertAPI as D, type E2EAction as E, createExpectAPI as F, type MockFunction as M, type PageObject as P, type SpyFunction as S, type TestCase as T, type VisualTestConfig as V, type AccessibilityIncomplete as a, type AccessibilityNode as b, type AccessibilityPass as c, type AccessibilityResult as d, type AccessibilityViolation as e, type AssertAPI as f, AssertionError as g, type BrowserType as h, type E2EStep as i, type ExpectAPI as j, type ExpectMatcher as k, type PerformanceMetrics as l, type TestConfig as m, type TestContext as n, type TestDataProvider as o, type TestDiscoveryOptions as p, type TestEnvironment as q, type TestError as r, type TestFixture as s, type TestFunction as t, type TestLog as u, type TestReporter as v, type TestResult as w, type TestRunner as x, type TestStatus as y, type TestSuite as z };
+export { type AccessibilityCheckResult as A, type BrowserType as B, type CoverageData as C, createAssertAPI as D, type E2EAction as E, createExpectAPI as F, type MockFunction as M, type PerformanceMetrics as P, type SpyFunction as S, type TestRunner as T, type VisualTestConfig as V, type TestSuite as a, type TestConfig as b, type TestResult as c, type TestCase as d, type TestContext as e, type PageObject as f, type TestFunction as g, type TestEnvironment as h, type AccessibilityIncomplete as i, type AccessibilityNode as j, type AccessibilityPass as k, type AccessibilityResult as l, type AccessibilityViolation as m, type AssertAPI as n, AssertionError as o, type BrowserTestOptions as p, type E2EStep as q, type ExpectAPI as r, type ExpectMatcher as s, type TestDataProvider as t, type TestDiscoveryOptions as u, type TestError as v, type TestFixture as w, type TestLog as x, type TestReporter as y, type TestStatus as z };

package/dist/{assertions-CthVynH6.d.ts → assertions-CsGP61iW.d.ts}

@@ -455,4 +455,4 @@ declare function createExpectAPI(): ExpectAPI;
  */
 declare function createAssertAPI(): AssertAPI;
 
-export { type AccessibilityCheckResult as A, type BrowserTestOptions as B, type CoverageData as C, createAssertAPI as D, type E2EAction as E, createExpectAPI as F, type MockFunction as M, type PageObject as P, type SpyFunction as S, type TestCase as T, type VisualTestConfig as V, type AccessibilityIncomplete as a, type AccessibilityNode as b, type AccessibilityPass as c, type AccessibilityResult as d, type AccessibilityViolation as e, type AssertAPI as f, AssertionError as g, type BrowserType as h, type E2EStep as i, type ExpectAPI as j, type ExpectMatcher as k, type PerformanceMetrics as l, type TestConfig as m, type TestContext as n, type TestDataProvider as o, type TestDiscoveryOptions as p, type TestEnvironment as q, type TestError as r, type TestFixture as s, type TestFunction as t, type TestLog as u, type TestReporter as v, type TestResult as w, type TestRunner as x, type TestStatus as y, type TestSuite as z };
+export { type AccessibilityCheckResult as A, type BrowserType as B, type CoverageData as C, createAssertAPI as D, type E2EAction as E, createExpectAPI as F, type MockFunction as M, type PerformanceMetrics as P, type SpyFunction as S, type TestRunner as T, type VisualTestConfig as V, type TestSuite as a, type TestConfig as b, type TestResult as c, type TestCase as d, type TestContext as e, type PageObject as f, type TestFunction as g, type TestEnvironment as h, type AccessibilityIncomplete as i, type AccessibilityNode as j, type AccessibilityPass as k, type AccessibilityResult as l, type AccessibilityViolation as m, type AssertAPI as n, AssertionError as o, type BrowserTestOptions as p, type E2EStep as q, type ExpectAPI as r, type ExpectMatcher as s, type TestDataProvider as t, type TestDiscoveryOptions as u, type TestError as v, type TestFixture as w, type TestLog as x, type TestReporter as y, type TestStatus as z };

package/dist/assertions.d.mts

@@ -1 +1 @@
-export { g as AssertionError, D as createAssertAPI, F as createExpectAPI } from './assertions-CthVynH6.mjs';
+export { o as AssertionError, D as createAssertAPI, F as createExpectAPI } from './assertions-CsGP61iW.mjs';

package/dist/assertions.d.ts

@@ -1 +1 @@
-export { g as AssertionError, D as createAssertAPI, F as createExpectAPI } from './assertions-CthVynH6.js';
+export { o as AssertionError, D as createAssertAPI, F as createExpectAPI } from './assertions-CsGP61iW.js';

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { x as TestRunner, z as TestSuite, m as TestConfig, w as TestResult, T as TestCase, n as TestContext, l as PerformanceMetrics, M as MockFunction, P as PageObject, S as SpyFunction, t as TestFunction, q as TestEnvironment, h as BrowserType } from './assertions-CthVynH6.mjs';
-export { A as AccessibilityCheckResult, a as AccessibilityIncomplete, b as AccessibilityNode, c as AccessibilityPass, d as AccessibilityResult, e as AccessibilityViolation, f as AssertAPI, g as AssertionError, B as BrowserTestOptions, C as CoverageData, E as E2EAction, i as E2EStep, j as ExpectAPI, k as ExpectMatcher, o as TestDataProvider, p as TestDiscoveryOptions, r as TestError, s as TestFixture, u as TestLog, v as TestReporter, y as TestStatus, V as VisualTestConfig, D as createAssertAPI, F as createExpectAPI } from './assertions-CthVynH6.mjs';
+import { T as TestRunner, a as TestSuite, b as TestConfig, c as TestResult, d as TestCase, e as TestContext, P as PerformanceMetrics, M as MockFunction, f as PageObject, S as SpyFunction, g as TestFunction, h as TestEnvironment, B as BrowserType } from './assertions-CsGP61iW.mjs';
+export { A as AccessibilityCheckResult, i as AccessibilityIncomplete, j as AccessibilityNode, k as AccessibilityPass, l as AccessibilityResult, m as AccessibilityViolation, n as AssertAPI, o as AssertionError, p as BrowserTestOptions, C as CoverageData, E as E2EAction, q as E2EStep, r as ExpectAPI, s as ExpectMatcher, t as TestDataProvider, u as TestDiscoveryOptions, v as TestError, w as TestFixture, x as TestLog, y as TestReporter, z as TestStatus, V as VisualTestConfig, D as createAssertAPI, F as createExpectAPI } from './assertions-CsGP61iW.mjs';
 
 /**
  * Test Runner

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { x as TestRunner, z as TestSuite, m as TestConfig, w as TestResult, T as TestCase, n as TestContext, l as PerformanceMetrics, M as MockFunction, P as PageObject, S as SpyFunction, t as TestFunction, q as TestEnvironment, h as BrowserType } from './assertions-CthVynH6.js';
-export { A as AccessibilityCheckResult, a as AccessibilityIncomplete, b as AccessibilityNode, c as AccessibilityPass, d as AccessibilityResult, e as AccessibilityViolation, f as AssertAPI, g as AssertionError, B as BrowserTestOptions, C as CoverageData, E as E2EAction, i as E2EStep, j as ExpectAPI, k as ExpectMatcher, o as TestDataProvider, p as TestDiscoveryOptions, r as TestError, s as TestFixture, u as TestLog, v as TestReporter, y as TestStatus, V as VisualTestConfig, D as createAssertAPI, F as createExpectAPI } from './assertions-CthVynH6.js';
+import { T as TestRunner, a as TestSuite, b as TestConfig, c as TestResult, d as TestCase, e as TestContext, P as PerformanceMetrics, M as MockFunction, f as PageObject, S as SpyFunction, g as TestFunction, h as TestEnvironment, B as BrowserType } from './assertions-CsGP61iW.js';
+export { A as AccessibilityCheckResult, i as AccessibilityIncomplete, j as AccessibilityNode, k as AccessibilityPass, l as AccessibilityResult, m as AccessibilityViolation, n as AssertAPI, o as AssertionError, p as BrowserTestOptions, C as CoverageData, E as E2EAction, q as E2EStep, r as ExpectAPI, s as ExpectMatcher, t as TestDataProvider, u as TestDiscoveryOptions, v as TestError, w as TestFixture, x as TestLog, y as TestReporter, z as TestStatus, V as VisualTestConfig, D as createAssertAPI, F as createExpectAPI } from './assertions-CsGP61iW.js';
 
 /**
  * Test Runner

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperfixi/testing-framework",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Cross-platform behavior testing suite for LokaScript applications",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -44,6 +44,7 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
+    "pretest": "../../scripts/ensure-fresh.sh ../intent ../framework ../semantic ../patterns-reference ../core",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
@@ -55,7 +56,7 @@
     "typecheck": "tsc --noEmit",
     "lint": "eslint src --ext ts,tsx",
     "lint:fix": "eslint src --ext ts,tsx --fix",
-    "test:check": "vitest run --reporter=dot 2>&1 | tail -5"
+    "test:check": "VITEST_QUIET=1 bash ../../scripts/vitest-run.sh --reporter=dot"
   },
   "keywords": [
     "hyperscript",
@@ -71,9 +72,9 @@
   "author": "LokaScript Contributors",
   "license": "MIT",
   "dependencies": {
-    "@hyperfixi/core": "^2.5.0",
-    "@hyperfixi/patterns-reference": "^2.5.0",
-    "@lokascript/semantic": "^2.5.0",
+    "@hyperfixi/core": "^2.6.0",
+    "@hyperfixi/patterns-reference": "^2.6.0",
+    "@lokascript/semantic": "^2.6.0",
     "diff": "^8.0.3",
     "esbuild": "^0.28.0",
     "happy-dom": "^20.8.9",

package/src/multilingual/bundle-builder.ts

@@ -121,6 +121,16 @@ export async function findBundleForLanguages(
   }
 
   if (!bestBundle) {
+    // Fallback: a per-language bundle `browser-{lang}.{lang}.global.js` may exist
+    // even when no predefined group covers the language (these are emitted by the
+    // semantic build for every individual language).
+    if (languages.length === 1) {
+      const name = `browser-${languages[0]}`;
+      const p = getBundlePath(name);
+      if (existsSync(p)) {
+        return { name, path: p, languages, size: statSync(p).size, exists: true };
+      }
+    }
     return null;
   }
 
@@ -163,8 +173,13 @@ export async function getBundleInfo(bundleName: string): Promise<BundleInfo | nu
 export async function buildBundle(options: BundleBuildOptions): Promise<BundleInfo> {
   const { languages, groupName } = options;
 
-  // Generate bundle using the generate-bundle.mjs script
-  const semanticRoot = join(process.cwd(), 'packages/semantic');
+  // Generate bundle using the generate-bundle.mjs script.
+  // Anchor to this file's location (not process.cwd()): when the gate runs via
+  // `npm run … --workspace=@hyperfixi/testing-framework`, cwd is the workspace
+  // package dir, so `cwd()/packages/semantic` resolves to a non-existent path and
+  // exec() fails with `spawn /bin/sh ENOENT`. getBundlePath() already resolves the
+  // semantic root this way — mirror it here.
+  const semanticRoot = join(__dirname, '../../..', 'semantic');
   const scriptPath = join(semanticRoot, 'scripts/generate-bundle.mjs');
 
   let bundleName: string;
@@ -210,32 +225,35 @@ export async function selectBundle(
   languages: LanguageCode[],
   build: boolean = false
 ): Promise<BundleInfo> {
-  // First, try to find existing bundle
-  let bundle = await findBundleForLanguages(languages);
+  // First, try to find an existing bundle
+  const bundle = await findBundleForLanguages(languages);
 
-  // If bundle exists and we don't need to build, use it
-  if (bundle && bundle.exists && !build) {
+  if (bundle && bundle.exists) {
     return bundle;
   }
 
-  // If build is requested or no bundle exists, build it
-  if (build || !bundle || !bundle.exists) {
-    // Determine if we can use a predefined group
+  // Build only on explicit request. The regression gate parses in-process (via
+  // parseSemantic), so the bundle is consumed only for size/existence reporting —
+  // a missing display bundle must NOT silently trigger a heavy on-demand semantic
+  // rebuild as a side effect of running tests.
+  if (build) {
     const groupName = findGroupForLanguages(languages);
-
-    bundle = await buildBundle({
+    const built = await buildBundle({
       languages,
       groupName: groupName !== null ? groupName : undefined,
       outputPath: undefined,
       updateConfig: false, // Don't modify configs during testing
     });
+    if (!built.exists) {
+      throw new Error(`Bundle not found: ${built.path}`);
+    }
+    return built;
   }
 
-  if (!bundle.exists) {
-    throw new Error(`Bundle not found: ${bundle.path}`);
-  }
-
-  return bundle;
+  // Not building: return what we know (possibly non-existent). The caller reports
+  // it as unavailable and continues with the in-process parse.
+  const name = `browser-${languages.join('-')}`;
+  return bundle ?? { name, path: getBundlePath(name), languages, size: 0, exists: false };
 }
 
 /**

package/src/multilingual/cli.ts

@@ -5,10 +5,62 @@
  * Command-line interface for running multilingual tests.
  */
 
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { checkDbStamp, getDefaultDbPath } from '@hyperfixi/patterns-reference';
 import { TestOrchestrator } from './orchestrator';
-import { RegressionReporter } from './reporters/regression-reporter';
 import type { TestConfig, LanguageCode } from './types';
 
+/**
+ * Packages whose dist/ this harness executes (directly or via imports), in
+ * topological build order. The sibling of the patterns.db provenance stamp:
+ * a sweep against a stale dist scores code that differs from the checkout.
+ */
+const DIST_GUARD_PACKAGES = [
+  'intent',
+  'framework',
+  'semantic',
+  'i18n',
+  'patterns-reference',
+  'core',
+];
+
+/** True if any .ts under dir is newer than builtAt (early-exit walk). */
+function hasNewerTs(dir: string, builtAt: number): boolean {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (hasNewerTs(p, builtAt)) return true;
+    } else if (entry.name.endsWith('.ts') && fs.statSync(p).mtimeMs > builtAt) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Names of guard packages whose src/ is newer than their built dist/ (or whose
+ * dist/ is missing entirely). Same staleness semantics as
+ * scripts/ensure-fresh.sh, but read-only — the CLI refuses instead of
+ * rebuilding, so a gate/baseline run never silently mutates build state.
+ */
+function findStaleDists(): string[] {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const packagesRoot = path.resolve(here, '../../..');
+  const stale: string[] = [];
+  for (const name of DIST_GUARD_PACKAGES) {
+    const pkg = path.join(packagesRoot, name);
+    const srcDir = path.join(pkg, 'src');
+    const marker = path.join(pkg, 'dist', 'index.js');
+    if (!fs.existsSync(srcDir)) continue;
+    if (!fs.existsSync(marker) || hasNewerTs(srcDir, fs.statSync(marker).mtimeMs)) {
+      stale.push(name);
+    }
+  }
+  return stale;
+}
+
 /**
  * Parse command-line arguments
  */
@@ -19,6 +71,11 @@ function parseArgs(): TestConfig {
     quickModeLimit: 10,
   };
 
+  // Track whether quick mode was explicitly requested, so --regression can safely
+  // upgrade the default-quick run to full (where the fidelity/degenerate ratchet
+  // actually runs) without overriding an explicit --quick.
+  let explicitQuick = false;
+
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
 
@@ -48,12 +105,16 @@ function parseArgs(): TestConfig {
         break;
 
       case '--mode':
-      case '-m':
-        config.mode = args[++i] as 'quick' | 'full';
+      case '-m': {
+        const mode = args[++i] as 'quick' | 'full';
+        config.mode = mode;
+        if (mode === 'quick') explicitQuick = true;
         break;
+      }
 
       case '--quick':
         config.mode = 'quick';
+        explicitQuick = true;
         break;
 
       case '--full':
@@ -70,6 +131,12 @@ function parseArgs(): TestConfig {
         config.regression = true;
         break;
 
+      case '--baseline': {
+        const path = args[++i];
+        if (path) config.baselinePath = path;
+        break;
+      }
+
       case '--confidence':
       case '-c': {
         const conf = args[++i];
@@ -100,9 +167,10 @@ function parseArgs(): TestConfig {
         break;
 
       case '--save-baseline':
-        // Special flag to save results as baseline
-        runAndSaveBaseline();
-        return config; // Early return to avoid running tests below
+        // Run the suite, then persist the results as the committed baseline
+        // (handled in main() — see saveBaseline below).
+        config.saveBaseline = true;
+        break;
 
       default:
         if (arg && arg.startsWith('-')) {
@@ -113,6 +181,20 @@ function parseArgs(): TestConfig {
     }
   }
 
+  // The regression gate ratchets on degenerate/fidelity passes, which are only
+  // computed in full mode. A default-quick --regression run silently checks just
+  // parse rate — a much weaker gate. Upgrade to full unless the caller explicitly
+  // asked for quick (in which case warn that the fidelity ratchet is skipped).
+  if (config.regression && config.mode === 'quick') {
+    if (explicitQuick) {
+      console.warn(
+        '⚠ --regression in --quick mode only checks parse rate; the degenerate/fidelity ratchet requires --full.'
+      );
+    } else {
+      config.mode = 'full';
+    }
+  }
+
   return config;
 }
 
@@ -135,7 +217,11 @@ OPTIONS:
       --quick                  Quick mode (10 patterns per language)
       --full                   Full mode (all patterns)
   -v, --verbose                Enable verbose output
-  -r, --regression             Compare to baseline and report regressions
+  -r, --regression             Gate on regressions vs baseline (exit 1 if any).
+                               Implies --full (the degenerate/fidelity ratchet
+                               needs full mode); pass --quick to force parse-rate-
+                               only and skip it.
+      --baseline <path>        Baseline file (default: ./baselines/multilingual-priority.json)
   -c, --confidence <n>         Minimum confidence threshold (0-1)
       --verified-only          Only test verified translations
       --categories <cats>      Filter by categories (comma-separated)
@@ -162,49 +248,283 @@ EXAMPLES:
 }
 
 /**
- * Run tests and save as baseline
+ * Main CLI entry point
  */
-async function runAndSaveBaseline(): Promise<void> {
+async function main(): Promise<void> {
   try {
-    // Parse config without --save-baseline
-    const args = process.argv.slice(2).filter(arg => arg !== '--save-baseline');
-    process.argv = [...process.argv.slice(0, 2), ...args];
-
     const config = parseArgs();
-    config.regression = true; // Enable regression reporter
+
+    // --save-baseline needs the regression reporter wired so it can persist.
+    if (config.saveBaseline) config.regression = true;
+
+    // DB freshness guard: refuse to run a regression/baseline compare against a
+    // patterns.db generated from *different* source than is currently checked out
+    // (the cross-branch "phantom regression" footgun). The committed baseline only
+    // pairs with a DB synced from the matching source. CI re-syncs before the gate,
+    // so it always passes; locally this catches a stale DB after a branch switch or
+    // an un-re-synced source edit.
+    if (config.regression) {
+      const dbPath = getDefaultDbPath();
+      const stamp = checkDbStamp(dbPath);
+      if (stamp.status === 'stale') {
+        console.error(
+          '\n✗ patterns.db is STALE — it was generated from different source than is currently\n' +
+            '  checked out, so a comparison against the committed baseline would report phantom\n' +
+            '  regressions. Re-sync it before running the gate:\n\n' +
+            '    npm run db:init:force --prefix packages/patterns-reference\n' +
+            '    npm run sync:translations --prefix packages/patterns-reference\n'
+        );
+        process.exit(1);
+      } else if (stamp.status === 'unstamped') {
+        console.warn(
+          '⚠ patterns.db has no provenance stamp (generated before the freshness guard); ' +
+            'cannot verify it is fresh. Re-sync if results look surprising.'
+        );
+      }
+
+      // Dist freshness guard (the db stamp's sibling): this CLI is normally
+      // invoked via `npx tsx`, which skips the pretest ensure-fresh hooks, and
+      // it executes the parser stack from dist/. A gate or --save-baseline run
+      // against a stale dist scores code that differs from the checkout — the
+      // "baseline saved from a transitional build" footgun (roadmap §7g/§10).
+      // Refuse rather than auto-rebuild so the run never mutates build state.
+      const staleDists = findStaleDists();
+      if (staleDists.length > 0) {
+        console.error(
+          `\n✗ Stale dist/ in: ${staleDists.join(', ')} — src/ is newer than the built output,\n` +
+            '  so this run would execute code that differs from the checkout (and a saved\n' +
+            '  baseline would not reproduce). Rebuild first:\n\n' +
+            staleDists.map(p => `    npm run build --prefix packages/${p}`).join('\n') +
+            '\n\n  (or rebuild the whole stack: npm run test:multilingual:build-deps)\n'
+        );
+        process.exit(1);
+      }
+    }
 
     const orchestrator = new TestOrchestrator(config);
     const results = await orchestrator.run();
 
-    // Save as baseline
-    const regressionReporter = orchestrator.getRegressionReporter();
-    if (regressionReporter) {
-      regressionReporter.saveAsBaseline(results);
-    } else {
-      // Create reporter and save
-      const reporter = new RegressionReporter();
+    // --save-baseline: write the current results as the committed baseline, done.
+    if (config.saveBaseline) {
+      const reporter = orchestrator.getRegressionReporter();
+      if (!reporter) {
+        console.error('✗ Could not create regression reporter to save baseline.');
+        process.exit(1);
+      }
       reporter.saveAsBaseline(results);
+      process.exit(0);
     }
 
-    process.exit(0);
-  } catch (error) {
-    console.error('Error:', error instanceof Error ? error.message : String(error));
-    process.exit(1);
-  }
-}
+    // Exit code:
+    //  - `--regression`: gate on regressions vs the committed baseline, NOT the
+    //    absolute pass rate. The full multilingual sweep has a KNOWN, documented
+    //    gap (newer feature patterns lack complete non-English coverage), so a
+    //    100%-or-fail gate would never go green. A language fails the gate when
+    //    its parse rate drops more than REGRESSION_TOLERANCE_PTS below baseline.
+    //    We deliberately gate on the RATE, not on per-pattern flips: a handful of
+    //    borderline-confidence patterns can flip pass/fail between builds without
+    //    a real regression (the per-pattern `newFailures` is kept for reporting
+    //    only). The baseline must be generated against a freshly `populate`d
+    //    patterns.db (CI re-populates), or every language reads as shifted.
+    //    Missing baseline → fail.
+    //  - otherwise: the normal absolute pass/fail (used by the quick-mode gate,
+    //    which is genuinely expected at 100%).
+    const REGRESSION_TOLERANCE_PTS = 2;
+    let exitCode: number;
+    if (config.regression) {
+      const reporter = orchestrator.getRegressionReporter();
+      if (!reporter?.hasBaseline()) {
+        console.error(
+          `✗ --regression set but no baseline found at ${config.baselinePath ?? './baselines/multilingual-priority.json'}. ` +
+            `Generate one with --save-baseline.`
+        );
+        exitCode = 1;
+      } else {
+        const allResults = reporter.getRegressionResults();
+        const regressed = allResults.filter(r => r.parseRateDelta < -REGRESSION_TOLERANCE_PTS);
+
+        // Fidelity ratchet: faithful baseline passes that became degenerate
+        // (parse non-null but lost most of the English command structure). A
+        // small tolerance absorbs residual baseline/DB noise — consistent with
+        // the parse-rate tolerance above — while catching real backsliding (a
+        // transformer change that degrades a whole cluster). Regenerate the
+        // baseline (with --save-baseline) after an intentional fidelity change.
+        const FIDELITY_REGRESSION_TOLERANCE = 3;
+        const fidelityRegressions = allResults.flatMap(r =>
+          r.newDegeneratePasses.map(id => `${r.language}/${id}`)
+        );
+
+        // R0 — correctness ratchet: catch *silent command-drops* the degenerate
+        // ratchet misses (a faithful 1.0 pass that becomes lossy, 0.5 ≤ fid < 1.0).
+        // Two complementary signals: (1) per-pattern faithful→lossy flips (precise),
+        // and (2) a per-language avgFidelity drop (coarse backstop — also catches
+        // lossy→more-lossy that the per-pattern flip can't see). Both are guarded by
+        // the baseline carrying the new `lossyPasses`/`avgFidelity` data, so an
+        // un-regenerated baseline never retro-flags. avgFidelity is deterministic
+        // (parse-derived, independent of the patterns.db confidence column), so the
+        // tolerance can be tight.
+        const LOSSY_REGRESSION_TOLERANCE = 3;
+        // 0.02 ≈ six single-pattern drops in a ~154-pattern language — absorbs any
+        // rare populate jitter while still catching real per-language cluster
+        // regressions (typically ≥0.03). The per-pattern lossy ratchet above is the
+        // precise primary signal; this is the coarse lossy→more-lossy backstop.
+        const AVG_FIDELITY_DROP_TOLERANCE = 0.02;
+        const lossyRegressions = allResults.flatMap(r =>
+          r.newLossyPasses.map(id => `${r.language}/${id}`)
+        );
+        const fidelityDrops = allResults.filter(
+          r => r.avgFidelityDelta < -AVG_FIDELITY_DROP_TOLERANCE
+        );
+
+        // R0-precision ratchet: same semantics as the avgFidelity ratchet, on
+        // the precision signal (fraction of each parse's actions justified by the
+        // en reference). A drop means a parser/render change started injecting
+        // phantom/spurious commands — invisible to recall. Deltas are 0 unless
+        // the baseline carries avgPrecision, so an un-regenerated baseline never
+        // retro-flags.
+        const AVG_PRECISION_DROP_TOLERANCE = 0.02;
+        const precisionDrops = allResults.filter(
+          r => r.avgPrecisionDelta < -AVG_PRECISION_DROP_TOLERANCE
+        );
+
+        // R1 — role-fidelity ratchet (§8): same semantics as the avgFidelity
+        // ratchet, on the role-recall signal (action.role:valueType vs the en
+        // reference). Deltas are 0 unless the baseline carries avgRoleFidelity,
+        // so an un-regenerated baseline never retro-flags. Slightly looser
+        // tolerance: role signatures are bigger sets, so populate jitter moves
+        // them a bit more than action sets.
+        const AVG_ROLE_FIDELITY_DROP_TOLERANCE = 0.02;
+        const roleFidelityDrops = allResults.filter(
+          r => r.avgRoleFidelityDelta < -AVG_ROLE_FIDELITY_DROP_TOLERANCE
+        );
+
+        // R2 — execution ratchet (§8): curated-subset patterns whose jsdom DOM
+        // effects matched the en reference in the baseline but diverge now.
+        // Tolerance 0: execution is binary and the harness is deterministic
+        // (two full probe sweeps were byte-identical), so ANY pass→fail flip is
+        // a real behavioral regression. Guarded by the baseline carrying
+        // executionFailures, so an un-regenerated baseline never retro-flags.
+        const executionRegressions = allResults.flatMap(r =>
+          r.newExecutionFailures.map(id => `${r.language}/${id}`)
+        );
+
+        let failed = false;
+
+        if (regressed.length > 0) {
+          console.error(
+            `\n✗ Regression vs baseline in ${regressed.length} language(s) ` +
+              `(parse rate dropped > ${REGRESSION_TOLERANCE_PTS}pts):`
+          );
+          for (const r of regressed) {
+            const fails = r.newFailures.length
+              ? ` — newly failing: ${r.newFailures.join(', ')}`
+              : '';
+            console.error(`   ${r.language}: ΔparseRate ${r.parseRateDelta.toFixed(1)}pts${fails}`);
+          }
+          failed = true;
+        }
 
-/**
- * Main CLI entry point
- */
-async function main(): Promise<void> {
-  try {
-    const config = parseArgs();
+        if (fidelityRegressions.length > FIDELITY_REGRESSION_TOLERANCE) {
+          console.error(
+            `\n✗ Fidelity regression vs baseline: ${fidelityRegressions.length} faithful pass(es) ` +
+              `became degenerate (tolerance ${FIDELITY_REGRESSION_TOLERANCE}):`
+          );
+          for (const id of fidelityRegressions) console.error(`   ${id}`);
+          console.error(
+            `   (parse non-null but lost >50% of the English command structure — ` +
+              `if intentional, regenerate the baseline with --save-baseline)`
+          );
+          failed = true;
+        } else if (fidelityRegressions.length > 0) {
+          console.warn(
+            `\n⚠ ${fidelityRegressions.length} fidelity regression(s) within tolerance ` +
+              `(${FIDELITY_REGRESSION_TOLERANCE}): ${fidelityRegressions.join(', ')}`
+          );
+        }
 
-    const orchestrator = new TestOrchestrator(config);
-    const results = await orchestrator.run();
+        if (lossyRegressions.length > LOSSY_REGRESSION_TOLERANCE) {
+          console.error(
+            `\n✗ Correctness regression vs baseline: ${lossyRegressions.length} faithful pass(es) ` +
+              `became lossy (silently dropped a command; tolerance ${LOSSY_REGRESSION_TOLERANCE}):`
+          );
+          for (const id of lossyRegressions) console.error(`   ${id}`);
+          console.error(
+            `   (still parses but lost ≥1 command vs the English reference — ` +
+              `if intentional, regenerate the baseline with --save-baseline)`
+          );
+          failed = true;
+        } else if (lossyRegressions.length > 0) {
+          console.warn(
+            `\n⚠ ${lossyRegressions.length} correctness regression(s) within tolerance ` +
+              `(${LOSSY_REGRESSION_TOLERANCE}): ${lossyRegressions.join(', ')}`
+          );
+        }
+
+        if (fidelityDrops.length > 0) {
+          console.error(
+            `\n✗ avgFidelity dropped > ${AVG_FIDELITY_DROP_TOLERANCE} in ` +
+              `${fidelityDrops.length} language(s):`
+          );
+          for (const r of fidelityDrops) {
+            console.error(`   ${r.language}: ΔavgFidelity ${r.avgFidelityDelta.toFixed(4)}`);
+          }
+          console.error(`   (if intentional, regenerate the baseline with --save-baseline)`);
+          failed = true;
+        }
+
+        if (precisionDrops.length > 0) {
+          console.error(
+            `\n✗ avgPrecision dropped > ${AVG_PRECISION_DROP_TOLERANCE} in ` +
+              `${precisionDrops.length} language(s) — a parse/render started injecting ` +
+              `phantom commands the source never had:`
+          );
+          for (const r of precisionDrops) {
+            console.error(`   ${r.language}: ΔavgPrecision ${r.avgPrecisionDelta.toFixed(4)}`);
+          }
+          console.error(`   (if intentional, regenerate the baseline with --save-baseline)`);
+          failed = true;
+        }
 
-    // Exit with appropriate code
-    const exitCode = results.summary.overallStatus === 'pass' ? 0 : 1;
+        if (roleFidelityDrops.length > 0) {
+          console.error(
+            `\n✗ avgRoleFidelity dropped > ${AVG_ROLE_FIDELITY_DROP_TOLERANCE} in ` +
+              `${roleFidelityDrops.length} language(s):`
+          );
+          for (const r of roleFidelityDrops) {
+            console.error(
+              `   ${r.language}: ΔavgRoleFidelity ${r.avgRoleFidelityDelta.toFixed(4)}`
+            );
+          }
+          console.error(`   (if intentional, regenerate the baseline with --save-baseline)`);
+          failed = true;
+        }
+
+        if (executionRegressions.length > 0) {
+          console.error(
+            `\n✗ Execution regression vs baseline (R2): ${executionRegressions.length} ` +
+              `curated pattern(s) no longer reproduce the en reference's DOM effects:`
+          );
+          for (const id of executionRegressions) console.error(`   ${id}`);
+          console.error(
+            `   (executed faithfully in the baseline — if intentional, regenerate ` +
+              `the baseline with --save-baseline)`
+          );
+          failed = true;
+        }
+
+        if (failed) {
+          exitCode = 1;
+        } else {
+          console.log(
+            `\n✓ No regression vs baseline ` +
+              `(parse-rate ${REGRESSION_TOLERANCE_PTS}pts, fidelity + correctness + execution ratchets).`
+          );
+          exitCode = 0;
+        }
+      }
+    } else {
+      exitCode = results.summary.overallStatus === 'pass' ? 0 : 1;
+    }
     process.exit(exitCode);
   } catch (error) {
     console.error('Error:', error instanceof Error ? error.message : String(error));