NAME

Developer::Dashboard::Pax::Differential - compare stock Perl execution with PAX capture behavior

SYNOPSIS

my $diff = Developer::Dashboard::Pax::Differential->new;
my $report = $diff->compare_capture('script.pl');

DESCRIPTION

Developer::Dashboard::Pax::Differential is an internal validation helper. It keeps differential capture checks available after SOW-03 removed pax capture from the public CLI by invoking Developer::Dashboard::Pax::Capture directly.

METHODS

new

Constructs a differential runner. The historical pax_bin argument is accepted for compatibility with older tests but no longer drives capture through the CLI.

compare_capture

Runs the entrypoint with stock Perl, captures it through Developer::Dashboard::Pax::Capture, and returns comparable exit/status metadata.

PURPOSE

This module exists to make stock-Perl versus PAX capture differences explicit when a behavior mismatch appears, instead of forcing contributors to debug the two paths manually from scratch.

WHY IT EXISTS

PAX's core promise is behavioral equivalence: a captured/compiled entrypoint should behave the same as running it under stock perl. That claim needs an automatic check, not a manual eyeballing of two separate runs, and the check needs to survive pax capture having been removed as a public SOW-03 CLI command (see Developer::Dashboard::Pax::CLI) - this module keeps the comparison alive internally by calling Developer::Dashboard::Pax::Capture directly rather than shelling out to a subcommand that no longer exists.

WHEN TO USE

Edit this file when the fields a differential comparison reports need to change (currently just exit-code and stderr-presence parity), or when compare_capture needs to account for a new way stock-Perl and captured execution could legitimately diverge.

HOW TO USE

Construct a Differential runner and call compare_capture with one entrypoint path. Read the returned pass flag first; the comparison sub-hash gives the specific stock/pax exit codes and stderr-presence flags that decided it, useful when pass is false and you need to see exactly where the two paths diverged.

WHAT USES IT

PAX's own internal validation/regression paths use this to catch a capture regression that would otherwise only surface as an opaque behavioral difference somewhere downstream in a built binary.

EXAMPLES

Example 1:

my $diff = Developer::Dashboard::Pax::Differential->new;
my $report = $diff->compare_capture('t/fixtures/simple.pl');
# $report->{pass} is true when both the stock and PAX-captured runs exit 0

Example 2:

if ( !$report->{pass} ) {
    warn "stock exit=$report->{comparison}{stock_exit} pax exit=$report->{comparison}{pax_exit}\n";
}