@fuzdev/fuz_util 0.54.0 → 0.56.0

package/dist/benchmark_baseline.js

@@ -65,8 +65,8 @@ const results_to_entries = (results) => {
 /**
  * Save benchmark results as the current baseline.
  *
- * @param results - Benchmark results to save
- * @param options - Save options
+ * @param results - benchmark results to save
+ * @param options - save options
  *
  * @example
  * ```ts
@@ -101,8 +101,8 @@ export const benchmark_baseline_save = async (results, options = {}) => {
 /**
  * Load the current baseline from disk.
  *
- * @param options - Load options
- * @returns The baseline, or null if not found or invalid
+ * @param options - load options
+ * @returns the baseline, or null if not found or invalid
  *
  * @example
  * ```ts
@@ -141,9 +141,9 @@ export const benchmark_baseline_load = async (options = {}) => {
 /**
  * Compare benchmark results against the stored baseline.
  *
- * @param results - Current benchmark results
- * @param options - Comparison options including regression threshold and staleness warning
- * @returns Comparison result with regressions, improvements, and unchanged tasks
+ * @param results - current benchmark results
+ * @param options - comparison options including regression threshold and staleness warning
+ * @returns comparison result with regressions, improvements, and unchanged tasks
  *
  * @example
  * ```ts
@@ -217,7 +217,9 @@ export const benchmark_baseline_compare = async (results, options = {}) => {
             sample_size: current.sample_size,
             confidence_interval_ns: stats_confidence_interval_from_summary(current.mean_ns, current.std_dev_ns, current.sample_size),
         };
-        const comparison = benchmark_stats_compare(baseline_stats, current_stats);
+        const comparison = benchmark_stats_compare(baseline_stats, current_stats, {
+            min_percent_difference: options.min_percent_difference,
+        });
         const task_comparison = {
             name: current.name,
             baseline: baseline_entry,
@@ -227,7 +229,8 @@ export const benchmark_baseline_compare = async (results, options = {}) => {
         comparisons.push(task_comparison);
         // Categorize based on comparison result
         // Note: comparison.faster is 'a' (baseline) or 'b' (current)
-        if (comparison.significant && comparison.effect_magnitude !== 'negligible') {
+        // significant implies percent_difference >= min_pct, which implies effect_magnitude !== 'negligible'
+        if (comparison.significant) {
             if (comparison.faster === 'a') {
                 // Baseline was faster = potential regression
                 // Only count as regression if it exceeds the threshold
@@ -256,10 +259,10 @@ export const benchmark_baseline_compare = async (results, options = {}) => {
             removed_tasks.push(baseline_entry.name);
         }
     }
-    // Sort regressions and improvements by effect size (largest first)
-    const sort_by_effect_size = (a, b) => b.comparison.effect_size - a.comparison.effect_size;
-    regressions.sort(sort_by_effect_size);
-    improvements.sort(sort_by_effect_size);
+    // Sort regressions and improvements by percentage difference (largest first)
+    const sort_by_percent_difference = (a, b) => b.comparison.percent_difference - a.comparison.percent_difference;
+    regressions.sort(sort_by_percent_difference);
+    improvements.sort(sort_by_percent_difference);
     return {
         baseline_found: true,
         baseline_timestamp: baseline.timestamp,
@@ -277,8 +280,8 @@ export const benchmark_baseline_compare = async (results, options = {}) => {
 /**
  * Format a baseline comparison result as a human-readable string.
  *
- * @param result - Comparison result from benchmark_baseline_compare
- * @returns Formatted string summary
+ * @param result - comparison result from `benchmark_baseline_compare`
+ * @returns formatted string summary
  */
 export const benchmark_baseline_format = (result) => {
     if (!result.baseline_found) {
@@ -302,8 +305,9 @@ export const benchmark_baseline_format = (result) => {
         lines.push(`Regressions (${result.regressions.length}):`);
         for (const r of result.regressions) {
             const ratio = r.comparison.speedup_ratio.toFixed(2);
+            const pct = (r.comparison.percent_difference * 100).toFixed(1);
             const p = r.comparison.p_value.toFixed(3);
-            lines.push(`  ${r.name}: ${ratio}x slower (p=${p}, ${r.comparison.effect_magnitude})`);
+            lines.push(`  ${r.name}: ${ratio}x slower (${pct}%, p=${p}, ${r.comparison.effect_magnitude})`);
         }
         lines.push('');
     }
@@ -311,8 +315,9 @@ export const benchmark_baseline_format = (result) => {
         lines.push(`Improvements (${result.improvements.length}):`);
         for (const r of result.improvements) {
             const ratio = r.comparison.speedup_ratio.toFixed(2);
+            const pct = (r.comparison.percent_difference * 100).toFixed(1);
             const p = r.comparison.p_value.toFixed(3);
-            lines.push(`  ${r.name}: ${ratio}x faster (p=${p}, ${r.comparison.effect_magnitude})`);
+            lines.push(`  ${r.name}: ${ratio}x faster (${pct}%, p=${p}, ${r.comparison.effect_magnitude})`);
         }
         lines.push('');
     }
@@ -345,8 +350,8 @@ export const benchmark_baseline_format = (result) => {
 /**
  * Format a baseline comparison result as JSON for programmatic consumption.
  *
- * @param result - Comparison result from benchmark_baseline_compare
- * @param options - Formatting options
+ * @param result - comparison result from `benchmark_baseline_compare`
+ * @param options - formatting options
  * @returns JSON string
  */
 export const benchmark_baseline_format_json = (result, options = {}) => {
@@ -367,6 +372,7 @@ export const benchmark_baseline_format_json = (result, options = {}) => {
         regressions: result.regressions.map((r) => ({
             name: r.name,
             speedup_ratio: r.comparison.speedup_ratio,
+            percent_difference: r.comparison.percent_difference,
             effect_size: r.comparison.effect_size,
             effect_magnitude: r.comparison.effect_magnitude,
             p_value: r.comparison.p_value,
@@ -376,6 +382,7 @@ export const benchmark_baseline_format_json = (result, options = {}) => {
         improvements: result.improvements.map((r) => ({
             name: r.name,
             speedup_ratio: r.comparison.speedup_ratio,
+            percent_difference: r.comparison.percent_difference,
             effect_size: r.comparison.effect_size,
             effect_magnitude: r.comparison.effect_magnitude,
             p_value: r.comparison.p_value,

package/dist/benchmark_format.d.ts

@@ -2,9 +2,9 @@ import type { BenchmarkResult, BenchmarkGroup } from './benchmark_types.js';
 /**
  * Format results as an ASCII table with percentiles, min/max, and relative performance.
  * All times use the same unit for easy comparison.
- * @param results - Array of benchmark results
- * @param baseline - Optional task name to use as baseline for comparison (defaults to fastest)
- * @returns Formatted table string with enhanced metrics
+ * @param results - array of benchmark results
+ * @param baseline - optional task name to use as baseline for comparison (defaults to fastest)
+ * @returns formatted table string with enhanced metrics
  *
  * @example
  * ```ts
@@ -21,9 +21,9 @@ export declare const benchmark_format_table: (results: Array<BenchmarkResult>, b
 /**
  * Format results as a Markdown table with key metrics.
  * All times use the same unit for easy comparison.
- * @param results - Array of benchmark results
- * @param baseline - Optional task name to use as baseline for comparison (defaults to fastest)
- * @returns Formatted markdown table string
+ * @param results - array of benchmark results
+ * @param baseline - optional task name to use as baseline for comparison (defaults to fastest)
+ * @returns formatted markdown table string
  *
  * @example
  * ```ts
@@ -37,9 +37,9 @@ export declare const benchmark_format_table: (results: Array<BenchmarkResult>, b
 export declare const benchmark_format_markdown: (results: Array<BenchmarkResult>, baseline?: string) => string;
 /**
  * Format results as grouped Markdown tables with headers between groups.
- * @param results - Array of benchmark results
- * @param groups - Array of group definitions
- * @returns Formatted markdown string with group headers and tables
+ * @param results - array of benchmark results
+ * @param groups - array of group definitions
+ * @returns formatted markdown string with group headers and tables
  *
  * @example
  * ```ts
@@ -68,8 +68,8 @@ export interface BenchmarkFormatJsonOptions {
 }
 /**
  * Format results as JSON.
- * @param results - Array of benchmark results
- * @param options - Formatting options
+ * @param results - array of benchmark results
+ * @param options - formatting options
  * @returns JSON string
  *
  * @example
@@ -82,9 +82,9 @@ export interface BenchmarkFormatJsonOptions {
 export declare const benchmark_format_json: (results: Array<BenchmarkResult>, options?: BenchmarkFormatJsonOptions) => string;
 /**
  * Format results as a grouped table with visual separators between groups.
- * @param results - Array of benchmark results
- * @param groups - Array of group definitions
- * @returns Formatted table string with group separators
+ * @param results - array of benchmark results
+ * @param groups - array of group definitions
+ * @returns formatted table string with group separators
  *
  * @example
  * ```ts
@@ -108,7 +108,7 @@ export declare const benchmark_format_json: (results: Array<BenchmarkResult>, op
 export declare const benchmark_format_table_grouped: (results: Array<BenchmarkResult>, groups: Array<BenchmarkGroup>) => string;
 /**
  * Format a number with fixed decimal places and thousands separators.
- * @see {@link format_number} in maths.ts for the underlying implementation.
+ * @see `format_number` in `maths.ts` for the underlying implementation.
  */
 export declare const benchmark_format_number: (n: number, decimals?: number) => string;
 //# sourceMappingURL=benchmark_format.d.ts.map

package/dist/benchmark_format.js

@@ -4,9 +4,9 @@ import { format_number } from './maths.js';
 /**
  * Format results as an ASCII table with percentiles, min/max, and relative performance.
  * All times use the same unit for easy comparison.
- * @param results - Array of benchmark results
- * @param baseline - Optional task name to use as baseline for comparison (defaults to fastest)
- * @returns Formatted table string with enhanced metrics
+ * @param results - array of benchmark results
+ * @param baseline - optional task name to use as baseline for comparison (defaults to fastest)
+ * @returns formatted table string with enhanced metrics
  *
  * @example
  * ```ts
@@ -105,9 +105,9 @@ export const benchmark_format_table = (results, baseline) => {
 /**
  * Format results as a Markdown table with key metrics.
  * All times use the same unit for easy comparison.
- * @param results - Array of benchmark results
- * @param baseline - Optional task name to use as baseline for comparison (defaults to fastest)
- * @returns Formatted markdown table string
+ * @param results - array of benchmark results
+ * @param baseline - optional task name to use as baseline for comparison (defaults to fastest)
+ * @returns formatted markdown table string
  *
  * @example
  * ```ts
@@ -200,9 +200,9 @@ export const benchmark_format_markdown = (results, baseline) => {
 };
 /**
  * Format results as grouped Markdown tables with headers between groups.
- * @param results - Array of benchmark results
- * @param groups - Array of group definitions
- * @returns Formatted markdown string with group headers and tables
+ * @param results - array of benchmark results
+ * @param groups - array of group definitions
+ * @returns formatted markdown string with group headers and tables
  *
  * @example
  * ```ts
@@ -248,8 +248,8 @@ export const benchmark_format_markdown_grouped = (results, groups) => {
 };
 /**
  * Format results as JSON.
- * @param results - Array of benchmark results
- * @param options - Formatting options
+ * @param results - array of benchmark results
+ * @param options - formatting options
  * @returns JSON string
  *
  * @example
@@ -290,9 +290,9 @@ export const benchmark_format_json = (results, options) => {
 };
 /**
  * Format results as a grouped table with visual separators between groups.
- * @param results - Array of benchmark results
- * @param groups - Array of group definitions
- * @returns Formatted table string with group separators
+ * @param results - array of benchmark results
+ * @param groups - array of group definitions
+ * @returns formatted table string with group separators
  *
  * @example
  * ```ts
@@ -339,6 +339,6 @@ export const benchmark_format_table_grouped = (results, groups) => {
 };
 /**
  * Format a number with fixed decimal places and thousands separators.
- * @see {@link format_number} in maths.ts for the underlying implementation.
+ * @see `format_number` in `maths.ts` for the underlying implementation.
  */
 export const benchmark_format_number = format_number;

package/dist/benchmark_stats.d.ts

@@ -1,6 +1,6 @@
 /**
  * Benchmark-specific statistical analysis.
- * Uses the general stats utilities from stats.ts for timing/performance analysis.
+ * Uses the general stats utilities from `stats.ts` for timing/performance analysis.
  * All timing values are in nanoseconds.
  *
  * @module
@@ -27,13 +27,15 @@ export interface BenchmarkComparison {
     faster: 'a' | 'b' | 'equal';
     /** How much faster the winner is (e.g., 1.5 means 1.5x faster) */
     speedup_ratio: number;
-    /** Whether the difference is statistically significant at the given alpha */
+    /** Whether the difference is both statistically and practically significant */
     significant: boolean;
     /** P-value from Welch's t-test (lower = more confident the difference is real) */
     p_value: number;
-    /** Cohen's d effect size (magnitude of difference independent of sample size) */
+    /** Percentage difference between means as a ratio (0.05 = 5%, 1.0 = 100%) */
+    percent_difference: number;
+    /** Cohen's d effect size (informational — not used for classification) */
     effect_size: number;
-    /** Interpretation of effect size */
+    /** Interpretation of practical significance based on percentage difference */
     effect_magnitude: EffectMagnitude;
     /** Whether the 95% confidence intervals overlap */
     ci_overlap: boolean;
@@ -46,6 +48,20 @@ export interface BenchmarkComparison {
 export interface BenchmarkCompareOptions {
     /** Significance level for hypothesis testing (default: 0.05) */
     alpha?: number;
+    /**
+     * Minimum percentage difference to consider practically meaningful, as a ratio.
+     * Below this threshold, differences are classified as 'negligible' and
+     * `significant` is forced to `false`, regardless of p-value.
+     * This prevents the t-test's oversensitivity at large sample sizes from
+     * flagging system-level noise (thermal throttle, OS scheduler, cache pressure)
+     * as meaningful differences.
+     *
+     * Effect magnitude thresholds scale from this value:
+     * negligible < min, small < min*3, medium < min*5, large >= min*5.
+     *
+     * Default: 0.10 (10%).
+     */
+    min_percent_difference?: number;
 }
 /**
  * Complete statistical analysis of timing measurements.
@@ -94,13 +110,17 @@ export declare class BenchmarkStats {
     toString(): string;
 }
 /**
- * Compare two benchmark results for statistical significance.
- * Uses Welch's t-test (handles unequal variances) and Cohen's d effect size.
+ * Compare two benchmark results for practical and statistical significance.
+ * Uses percentage difference for effect magnitude classification, with Welch's
+ * t-test for statistical confidence. Cohen's d is computed as an informational
+ * metric but does not drive classification — its thresholds (0.2/0.5/0.8) are
+ * calibrated for social science and produce false positives in benchmarking
+ * where within-run variance is tight.
  *
- * @param a - First benchmark stats (or any object with required properties)
- * @param b - Second benchmark stats (or any object with required properties)
- * @param options - Comparison options
- * @returns Comparison result with significance, effect size, and recommendation
+ * @param a - first benchmark stats (or any object with required properties)
+ * @param b - second benchmark stats (or any object with required properties)
+ * @param options - comparison options
+ * @returns comparison result with significance, effect size, and recommendation
  *
  * @example
  * ```ts

package/dist/benchmark_stats.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"benchmark_stats.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/benchmark_stats.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAgBH;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,sBAAsB,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE1E;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,mFAAmF;IACnF,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,OAAO,CAAC;IAC5B,kEAAkE;IAClE,aAAa,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,WAAW,EAAE,OAAO,CAAC;IACrB,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,WAAW,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,gBAAgB,EAAE,eAAe,CAAC;IAClC,mDAAmD;IACnD,UAAU,EAAE,OAAO,CAAC;IACpB,sDAAsD;IACtD,cAAc,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACvC,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,qBAAa,cAAc;IAC1B,yCAAyC;IACzC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mDAAmD;IACnD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,wCAAwC;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,QAAQ,CAAC,sBAAsB,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClD,sDAAsD;IACtD,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACpC,yCAAyC;IACzC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,8CAA8C;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,0DAA0D;IAC1D,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,mDAAmD;IACnD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,sEAAsE;IACtE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;gBAEvB,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC;IAiErC;;OAEG;IACH,QAAQ,IAAI,MAAM;CAGlB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,uBAAuB,GACnC,GAAG,wBAAwB,EAC3B,GAAG,wBAAwB,EAC3B,UAAU,uBAAuB,KAC/B,mBA6GF,CAAC"}
+{"version":3,"file":"benchmark_stats.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/benchmark_stats.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAgBH;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,sBAAsB,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE1E;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,mFAAmF;IACnF,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,OAAO,CAAC;IAC5B,kEAAkE;IAClE,aAAa,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,WAAW,EAAE,OAAO,CAAC;IACrB,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,kBAAkB,EAAE,MAAM,CAAC;IAC3B,0EAA0E;IAC1E,WAAW,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,gBAAgB,EAAE,eAAe,CAAC;IAClC,mDAAmD;IACnD,UAAU,EAAE,OAAO,CAAC;IACpB,sDAAsD;IACtD,cAAc,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACvC,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;;OAYG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;GAIG;AACH,qBAAa,cAAc;IAC1B,yCAAyC;IACzC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mDAAmD;IACnD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,wCAAwC;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,QAAQ,CAAC,sBAAsB,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClD,sDAAsD;IACtD,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACpC,yCAAyC;IACzC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,8CAA8C;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,0DAA0D;IAC1D,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,mDAAmD;IACnD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,sEAAsE;IACtE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;gBAEvB,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC;IAiErC;;OAEG;IACH,QAAQ,IAAI,MAAM;CAGlB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,uBAAuB,GACnC,GAAG,wBAAwB,EAC3B,GAAG,wBAAwB,EAC3B,UAAU,uBAAuB,KAC/B,mBA+GF,CAAC"}

package/dist/benchmark_stats.js

@@ -1,6 +1,6 @@
 /**
  * Benchmark-specific statistical analysis.
- * Uses the general stats utilities from stats.ts for timing/performance analysis.
+ * Uses the general stats utilities from `stats.ts` for timing/performance analysis.
  * All timing values are in nanoseconds.
  *
  * @module
@@ -110,13 +110,17 @@ export class BenchmarkStats {
     }
 }
 /**
- * Compare two benchmark results for statistical significance.
- * Uses Welch's t-test (handles unequal variances) and Cohen's d effect size.
+ * Compare two benchmark results for practical and statistical significance.
+ * Uses percentage difference for effect magnitude classification, with Welch's
+ * t-test for statistical confidence. Cohen's d is computed as an informational
+ * metric but does not drive classification — its thresholds (0.2/0.5/0.8) are
+ * calibrated for social science and produce false positives in benchmarking
+ * where within-run variance is tight.
  *
- * @param a - First benchmark stats (or any object with required properties)
- * @param b - Second benchmark stats (or any object with required properties)
- * @param options - Comparison options
- * @returns Comparison result with significance, effect size, and recommendation
+ * @param a - first benchmark stats (or any object with required properties)
+ * @param b - second benchmark stats (or any object with required properties)
+ * @param options - comparison options
+ * @returns comparison result with significance, effect size, and recommendation
  *
  * @example
  * ```ts
@@ -128,6 +132,7 @@ export class BenchmarkStats {
  */
 export const benchmark_stats_compare = (a, b, options) => {
     const alpha = options?.alpha ?? 0.05;
+    const min_pct = options?.min_percent_difference ?? 0.1;
     // Handle edge cases
     if (a.sample_size === 0 || b.sample_size === 0) {
         return {
@@ -135,6 +140,7 @@ export const benchmark_stats_compare = (a, b, options) => {
             speedup_ratio: 1,
             significant: false,
             p_value: 1,
+            percent_difference: 0,
             effect_size: 0,
             effect_magnitude: 'negligible',
             ci_overlap: true,
@@ -144,6 +150,8 @@ export const benchmark_stats_compare = (a, b, options) => {
     // Calculate speedup ratio (lower time = faster, so compare by time not ops/sec)
     const speedup_ratio = a.mean_ns < b.mean_ns ? b.mean_ns / a.mean_ns : a.mean_ns / b.mean_ns;
     const faster = a.mean_ns < b.mean_ns ? 'a' : a.mean_ns > b.mean_ns ? 'b' : 'equal';
+    // Percentage difference relative to the faster mean (always >= 0)
+    const percent_difference = speedup_ratio - 1;
     // Welch's t-test (handles unequal variances)
     // Special case: if both have zero variance, t-test is undefined
     let p_value;
@@ -156,55 +164,54 @@ export const benchmark_stats_compare = (a, b, options) => {
         // Calculate two-tailed p-value using t-distribution approximation
         p_value = stats_t_distribution_p_value(Math.abs(t_statistic), degrees_of_freedom);
     }
-    // Cohen's d effect size
+    // Cohen's d effect size (informational only — not used for classification)
     const pooled_std_dev = Math.sqrt(((a.sample_size - 1) * a.std_dev_ns ** 2 + (b.sample_size - 1) * b.std_dev_ns ** 2) /
         (a.sample_size + b.sample_size - 2));
-    // When pooled_std_dev is 0 but means differ, effect is maximal (infinite)
-    // When means are equal, effect is 0
     let effect_size;
-    let effect_magnitude;
     if (pooled_std_dev === 0) {
-        // Zero variance case - if means differ, it's a definitive difference
-        if (a.mean_ns === b.mean_ns) {
-            effect_size = 0;
-            effect_magnitude = 'negligible';
-        }
-        else {
-            // Any difference is 100% reliable when there's no variance
-            effect_size = Infinity;
-            effect_magnitude = 'large';
-        }
+        effect_size = a.mean_ns === b.mean_ns ? 0 : Infinity;
     }
     else {
         effect_size = Math.abs(a.mean_ns - b.mean_ns) / pooled_std_dev;
-        // Interpret effect size (Cohen's conventions)
-        effect_magnitude =
-            effect_size < 0.2
-                ? 'negligible'
-                : effect_size < 0.5
-                    ? 'small'
-                    : effect_size < 0.8
-                        ? 'medium'
-                        : 'large';
+    }
+    // Effect magnitude based on percentage difference, not Cohen's d.
+    // Cohen's d thresholds (0.2/0.5/0.8) are calibrated for social science, not benchmarking.
+    // Within-run variance is tight, so even small system noise (thermal throttle, OS scheduler)
+    // produces large Cohen's d. Percentage thresholds directly answer "is this difference
+    // meaningful in practice?" Thresholds scale with min_percent_difference so users can
+    // tune one knob for their system's noise floor.
+    let effect_magnitude;
+    if (percent_difference < min_pct) {
+        effect_magnitude = 'negligible';
+    }
+    else if (percent_difference < min_pct * 3) {
+        effect_magnitude = 'small';
+    }
+    else if (percent_difference < min_pct * 5) {
+        effect_magnitude = 'medium';
+    }
+    else {
+        effect_magnitude = 'large';
     }
     // Check confidence interval overlap
     const ci_overlap = a.confidence_interval_ns[0] <= b.confidence_interval_ns[1] &&
         b.confidence_interval_ns[0] <= a.confidence_interval_ns[1];
-    // Determine significance
-    const significant = p_value < alpha;
+    // Significance requires both statistical significance (p < alpha)
+    // AND practical significance (percent_difference >= min_pct).
+    // With large n, the t-test finds p≈0 for any difference because
+    // SE = std_dev/sqrt(n) → 0. Gating on practical significance
+    // prevents system noise from being flagged as meaningful.
+    const significant = p_value < alpha && percent_difference >= min_pct;
     // Generate recommendation
     let recommendation;
-    if (!significant) {
-        recommendation =
-            effect_magnitude === 'negligible'
-                ? 'No meaningful difference detected'
-                : `Difference not statistically significant (p=${p_value.toFixed(3)}), but effect size suggests ${effect_magnitude} practical difference`;
+    if (percent_difference < min_pct) {
+        recommendation = 'No meaningful difference detected';
     }
-    else if (effect_magnitude === 'negligible') {
-        recommendation = `Statistically significant but negligible practical difference (${speedup_ratio.toFixed(2)}x)`;
+    else if (!significant) {
+        recommendation = `${(percent_difference * 100).toFixed(1)}% difference observed but not statistically significant (p=${p_value.toFixed(3)})`;
     }
     else {
-        recommendation = `${faster === 'a' ? 'First' : 'Second'} is ${speedup_ratio.toFixed(2)}x faster with ${effect_magnitude} effect size (p=${p_value.toFixed(3)})`;
+        recommendation = `${faster === 'a' ? 'First' : 'Second'} is ${speedup_ratio.toFixed(2)}x faster with ${effect_magnitude} effect size (${(percent_difference * 100).toFixed(1)}%, p=${p_value.toFixed(3)})`;
     }
     // Adjust 'faster' to 'equal' if effect is negligible
     const adjusted_faster = effect_magnitude === 'negligible' ? 'equal' : faster;
@@ -213,6 +220,7 @@ export const benchmark_stats_compare = (a, b, options) => {
         speedup_ratio,
         significant,
         p_value,
+        percent_difference,
         effect_size,
         effect_magnitude,
         ci_overlap,

package/dist/benchmark_types.d.ts

@@ -35,7 +35,7 @@ export interface BenchmarkConfig {
     max_iterations?: number;
     /**
      * Custom timer to use for measurements.
-     * Default: timer_default (auto-detects environment)
+     * Default: `timer_default` (auto-detects environment)
      */
     timer?: Timer;
     /**
@@ -47,9 +47,9 @@ export interface BenchmarkConfig {
      * after the timing capture. However, frequent GC calls will slow overall benchmark
      * execution time.
      *
-     * @param task_name - Name of the current task being benchmarked
-     * @param iteration - Current iteration number (1-indexed)
-     * @param abort - Call to stop the benchmark early for this task
+     * @param task_name - name of the current task being benchmarked
+     * @param iteration - current iteration number (1-indexed)
+     * @param abort - call to stop the benchmark early for this task
      *
      * @example
      * ```ts
@@ -82,9 +82,9 @@ export interface BenchmarkConfig {
      * Callback invoked after each task completes.
      * Useful for logging progress during long benchmark runs.
      *
-     * @param result - The completed benchmark result
-     * @param index - Zero-based index of the completed task
-     * @param total - Total number of tasks to run
+     * @param result - the completed benchmark result
+     * @param index - zero-based index of the completed task
+     * @param total - total number of tasks to run
      *
      * @example
      * ```ts

package/dist/bytes.d.ts

@@ -7,15 +7,15 @@
  * Converts string or binary data to a `Uint8Array`.
  * Strings are UTF-8 encoded. `Uint8Array` inputs are returned as-is.
  *
- * @param data - String or `BufferSource` to convert.
- * @returns `Uint8Array` view of the data.
+ * @param data - string or `BufferSource` to convert
+ * @returns `Uint8Array` view of the data
  */
 export declare const to_bytes: (data: BufferSource | string) => Uint8Array;
 /**
  * Formats a byte count as a human-readable string.
  *
- * @param n - byte count.
- * @returns formatted string like `'1.2 KB'` or `'3.4 MB'`.
+ * @param n - byte count
+ * @returns formatted string like `'1.2 KB'` or `'3.4 MB'`
  */
 export declare const format_bytes: (n: number) => string;
 //# sourceMappingURL=bytes.d.ts.map

package/dist/bytes.js

@@ -8,8 +8,8 @@ const encoder = new TextEncoder();
  * Converts string or binary data to a `Uint8Array`.
  * Strings are UTF-8 encoded. `Uint8Array` inputs are returned as-is.
  *
- * @param data - String or `BufferSource` to convert.
- * @returns `Uint8Array` view of the data.
+ * @param data - string or `BufferSource` to convert
+ * @returns `Uint8Array` view of the data
  */
 export const to_bytes = (data) => {
     if (typeof data === 'string')
@@ -23,8 +23,8 @@ export const to_bytes = (data) => {
 /**
  * Formats a byte count as a human-readable string.
  *
- * @param n - byte count.
- * @returns formatted string like `'1.2 KB'` or `'3.4 MB'`.
+ * @param n - byte count
+ * @returns formatted string like `'1.2 KB'` or `'3.4 MB'`
  */
 export const format_bytes = (n) => {
     if (n < 1024)

package/dist/dag.d.ts

@@ -73,8 +73,8 @@ export interface DagResult {
  * eligible to start. Failure cascading and stop-on-failure are handled
  * per the options.
  *
- * @param options - DAG execution options.
- * @returns Aggregated result with per-node details.
+ * @param options - DAG execution options
+ * @returns aggregated result with per-node details
  */
 export declare const run_dag: <T extends DagNode>(options: DagOptions<T>) => Promise<DagResult>;
 //# sourceMappingURL=dag.d.ts.map

package/dist/dag.js

@@ -18,8 +18,8 @@ import { topological_sort } from './sort.js';
  * eligible to start. Failure cascading and stop-on-failure are handled
  * per the options.
  *
- * @param options - DAG execution options.
- * @returns Aggregated result with per-node details.
+ * @param options - DAG execution options
+ * @returns aggregated result with per-node details
  */
 export const run_dag = async (options) => {
     const { nodes, execute, on_error, on_skip, should_skip, max_concurrency = Infinity, stop_on_failure = true, skip_validation = false, } = options;

package/dist/deep_equal.d.ts

@@ -10,8 +10,8 @@
  * - Promises always return false (cannot be meaningfully compared)
  * - Maps/Sets compare by reference for object keys/values
  *
- * @param a first value to compare
- * @param b second value to compare
+ * @param a - first value to compare
+ * @param b - second value to compare
  * @returns true if deeply equal, false otherwise
  */
 export declare const deep_equal: (a: unknown, b: unknown) => boolean;

package/dist/deep_equal.js

@@ -10,8 +10,8 @@
  * - Promises always return false (cannot be meaningfully compared)
  * - Maps/Sets compare by reference for object keys/values
  *
- * @param a first value to compare
- * @param b second value to compare
+ * @param a - first value to compare
+ * @param b - second value to compare
  * @returns true if deeply equal, false otherwise
  */
 export const deep_equal = (a, b) => {