# PCRE2 advanced slices

This document records the reviewed boundaries for advanced PCRE2 work. A
feature is exposed only after its complete runtime and UI path passes the
stated gates.

## Automatic-callout trace — implemented

ABI version 3 and the dedicated trace worker now provide:

- a new ABI operation separate from normal matching, compiled with
  `PCRE2_AUTO_CALLOUT`;
- a fixed copied event record containing only reported callout number, pattern
  byte position, next-item length, subject byte position, capture top/last and
  bounded mark text;
- caller-supplied event and text buffers capped by both
  `maximumTraceEvents` and `maximumTraceBytes`;
- explicit `eventsTruncated`, native status and last-complete-event fields;
- the existing match/depth/heap limits and supervisor timeout;
- cleanup identical to normal ABI calls.

Tracing runs in its own worker and never replaces the normal result used by
Match, Replace, Tests, Corpus or Analysis. “Forward”, “same position” and
“apparent backtrack” are derived from adjacent reported positions only and
carry derived provenance. The viewer explicitly states that a callout stream
is not a complete account of every internal engine action.

## ECMAScript versus PCRE2 comparison — implemented

The comparison orchestrator issues two explicit requests with
`Promise.allSettled` through independently killable flavour workers. It does
not translate flags, patterns or replacement syntax.

The comparison DTO retains:

- each exact request identity, engine identity and independently complete or
  timed-out result;
- match/capture differences aligned by editor UTF-16 ranges, while retaining
  each native offset model;
- explicit “not comparable” states for syntax/compile failure, truncation,
  timeout, cancellation, worker failure or flavour-only constructs;
- a shared wall-clock cancellation action that terminates both workers.

The orchestrator remains outside `EngineSupervisor`, preserving the
single-engine lifecycle boundary. Shared patterns are sent unchanged and
explicit per-flavour variants remain user-owned. Agreement is labelled only as
evidence for the current subject.

## PCRE2 C code generation — implemented

The first reviewed target consumes a validated request snapshot and uses an
application-owned C17 template. It:

- identifies exact PCRE2 10.47, 8-bit, UTF/UCP semantics and selected flags;
- emits pattern, subject and replacement independently as exact UTF-8 byte
  arrays;
- includes match/depth/heap limits and error handling in generated C examples;
- states when a target binding cannot express an application-level `g` flag or
  a Regex Tools output/result cap directly;
- ships deterministic golden match/replacement fixtures that compile and
  execute against official PCRE2 10.47 before the target is advertised.

No generated snippet may be used as the implementation of the browser runtime.
Other target languages remain unavailable until their own escaping and
toolchain gates pass. See
[`COMPARISON_AND_CODEGEN.md`](COMPARISON_AND_CODEGEN.md).
