# 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.