regex-tools/docs/PCRE2_NEXT_SLICES.md

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.