regex-tools/docs/EXECUTION_TRACES.md

Execution traces

Browser ECMAScript APIs expose compilation, match, capture and replacement results, but no V8, SpiderMonkey or JavaScriptCore execution trace. Regex Tools does not relabel structural explanations, static findings or timing observations as an ECMAScript engine trace.

The PHP, legacy Perl, CPython, CRuby, TeaVM Java/Scala compatibility, libc++, Go, Rust and .NET bridges likewise expose compilation, bounded match/capture and replacement results, not internal engine steps. Regex Tools does not label their partial lexical syntax trees as traces.

PCRE2 10.47 has a separate actual automatic-callout vertical. ABI version 3 compiles the requested pattern with PCRE2_AUTO_CALLOUT, registers an application callback, and copies only:

• callout number;
• pattern byte position and next-item byte length;
• subject byte position;
• capture-top and capture-last numbers;
• bounded current mark text.

These fields have reported provenance. Pattern and subject byte boundaries are validated and normalized to exact editor UTF-16 positions while the native values remain visible.

Collection runs in pcre2-trace.worker, not the normal execution worker. It uses the selected PCRE2 match, depth and heap limits plus the supervisor wall clock. The callback retains only complete 32-byte records and mark slices under both a 50,000-event and 10 MiB serialized-data hard cap. At a cap it returns PCRE2’s reserved PCRE2_ERROR_CALLOUT, abandoning the native match; the result retains that native status, the last complete event and an explicit truncation flag. Timeout, cancellation or crash discards the complete worker.

The viewer derives “forward”, “same position” and “apparent backtrack” solely from the difference between adjacent reported subject positions. Each label has derived provenance. This is useful navigation, not a claim that the stream reports every internal action. PCRE2 start optimizations can also conclude some requests without any callout.

Tracing represents one exact pcre2_match() invocation. The application-level g iteration flag is not applied, and that fact is reported. Normal match, replacement, tests, corpus, comparisons and benchmarks never use the instrumented trace path.