regex-tools/docs/MINIMIZATION.md

Subject minimization

The Minimize workspace reduces one failing subject locally against the selected real ECMAScript or PCRE2 worker. It can preserve:

• the exact failure class of any supported saved unit-test assertion;
• an identified capture's wrong participation, value or UTF-16 range;
• an engine worker timeout at one fixed deadline;
• an ECMAScript/PCRE2 semantic mismatch with the same mismatch-kind set; or
• the same one-sided comparison timeout while the other engine completes with authoritative, untruncated output.

PHP, Perl, Python, Ruby, Java, C++, Go, Rust, .NET and Scala compatibility are not supported minimization targets in v0.4.1. The workspace disables reduction for those active profiles; it does not substitute ECMAScript, PCRE2 or a lexical provider as an execution oracle.

The fixed pattern, ordered flags, options, replacement and engine versions form the target identity. Syntax is parsed once to obtain capture metadata. Every accepted subject candidate is then verified through the selected execution worker; the reducer does not contain a substitute regex implementation.

Deterministic transforms

Subjects must be well-formed Unicode. The reducer never splits a surrogate pair and rejects input containing a lone surrogate.

Reduction order is stable:

1. contiguous ddmin chunk deletion, left to right;
2. single Unicode-scalar deletion, left to right; then
3. lower-rank replacement by a, 0, space, newline and !, in that order.

The last two passes restart after every accepted change and continue to a fixed point. A complete pass with no accepted candidate establishes only local minimality under those transforms. It is not a proof of the shortest, globally minimal or semantically simplest reproducer. Evaluation or wall-budget exhaustion, an inconclusive candidate, cancellation and worker failure always return a result without a minimality claim.

Exact predicates

A baseline run must reproduce the requested failure before reduction starts. Unit-test failures retain their assertion class; a wrong capture value cannot turn into a missing capture, and a semantic comparison retains the exact sorted set of baseline mismatch kinds. Rejected patterns and truncated match, capture or replacement data are not accepted as semantic evidence.

Timeout is a worker deadline outcome, never a no-match. An explicit timeout predicate accepts only WorkerRequestError("timeout") at the configured fixed deadline. Comparison timeout reduction additionally requires the same flavour to time out and the peer flavour to complete with the same engine identity and complete data. Crash, unreadable worker response, ordinary worker error and cancellation have separate statuses. Crash minimization is unsupported and a crash never satisfies a timeout predicate.

For a must-time-out unit-test assertion, an ordinary completion is the test failure being minimized; a timeout makes that assertion pass. The separate Exact engine timeout target is used to minimize an observed timeout.

Bounds and progress

• Subject: 1 MiB UTF-8, separate from the larger interactive editor cap.
• Candidate evaluations: at most 2,000, including the baseline.
• Aggregate syntax-setup and reduction wall time: at most 60 seconds.
• Candidate worker deadline: fixed for the complete run, at most 10 seconds.
• Retained accepted-transform history: 200 entries; totals remain exact.

A candidate starts only when its full fixed deadline fits inside the remaining aggregate wall budget. This prevents the aggregate deadline from being misreported as an engine timeout. Progress exposes phase, evaluation and wall budgets, accepted reductions, current scalar/byte sizes and the latest observation. Cancellation terminates syntax and execution workers.

The minimized subject can be copied or deliberately applied to the main editor. Inputs and results stay in memory and are neither uploaded nor persisted.