feat: publish Regex Tools 0.2.0

docs/EXECUTION_TRACES.md

@@ -1,13 +1,39 @@
 # Execution traces
 
-Version 0.1.0 exposes no execution trace.
+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.
 
-Browser ECMAScript APIs return compilation, match, capture and replacement
-results but not the runtime's internal backtracking events. Regex Tools does
-not label structural explanations, static hints or adjacent-result inference
-as an actual engine trace.
+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:
 
-The next PCRE2 slice will use actual automatic/explicit callout events from an
-application-owned bridge. Event count, serialized bytes, match/depth/heap
-limits and wall-clock termination must all be enforced. Classifications such
-as “apparent backtrack” will remain visibly derived from adjacent events.
+- 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.