feat: publish Regex Tools 0.2.0

docs/ENGINE_BUILDS.md

@@ -1,28 +1,74 @@
 # Engine builds
 
-Version 0.1.0 ships no WebAssembly engine.
+The production application uses the browser's native `RegExp` for ECMAScript
+and bundles a verified PCRE2 10.47 WebAssembly pack. Normal application builds
+never download or compile an engine: the reviewed files under
+`public/engines/pcre2/` are copied into `dist/` and verified there.
 
-`npm run engines:build` verifies that this release has no external pack to
-build. After the production build, `npm run engines:verify` rejects any
-undeclared engine asset and confirms the packaged ECMAScript-only notice.
-Neither command accesses the network.
+## Rebuilding PCRE2
 
-## PCRE2 feasibility record
+The reproducible build accepts only:
 
-The next flavour was spiked outside the application repository against official
-PCRE2 10.47:
+- PCRE2 tag `pcre2-10.47`, signed tag object
+  `cd007b4466798f66d479d1442a407099e7c40050`, peeled commit
+  `f454e231fe5006dd7ff8f4693fd2b8eb94333429` and tree
+  `81a83a3552bd68d0ea7b7004f8bb6e7892f583ba`;
+- Emscripten 6.0.4, compiler revision
+  `fe5be6afdff43ad58860d821fcc8572a23f92d19`, from emsdk commit
+  `224ec5f9f2f72f09f9ce0e26d66bae7dbd8b692f`;
+- CMake 4.3.4 and Ninja 1.13.2;
+- 8-bit PCRE2 with Unicode enabled and JIT, threads and filesystem disabled.
 
-- signed tag object `cd007b4466798f66d479d1442a407099e7c40050`;
-- peeled commit `f454e231fe5006dd7ff8f4693fd2b8eb94333429`;
-- licence `BSD-3-Clause WITH PCRE2-exception`;
-- Emscripten 6.0.4;
-- 8-bit library, Unicode enabled, JIT disabled.
+The source and compiler checkouts must already exist locally and be completely
+clean. No command clones, downloads or updates them:
 
-Node and Chromium tests demonstrated version/config reporting, Unicode,
-named groups, global substitution, automatic and explicit callouts, and
-match/depth/heap errors. This was a technical spike only. No spike source,
-binary or PCRE2 source is included in v0.1.0.
+```sh
+npm run engines:pcre2:build -- \
+  --source-dir /absolute/path/to/pcre2 \
+  --emcc /absolute/path/to/emscripten/emcc
+npm run engines:pcre2:verify
+npm run engines:pcre2:install
+```
 
-Production PCRE2 support remains gated on a reviewed bridge, copied DTOs,
-allocation cleanup, exact source build, UTF-8/UTF-16 mapping, trace/output caps,
-worker recovery, deterministic assets, licences and browser conformance.
+Use `--force` only to replace the exact ignored `.engine-build/pcre2` output.
+The explicit install command first re-verifies that pack and then atomically
+replaces only `public/engines/pcre2`.
+
+The builder verifies Git objects and critical source/compiler hashes,
+sanitizes build flags, sets `SOURCE_DATE_EPOCH=1760997684`, builds serially and
+emits exactly:
+
+- `pcre2.mjs` and `pcre2.wasm`;
+- deterministic `engine-metadata.json`;
+- the exact upstream `LICENSE.txt`;
+- `SHA256SUMS`.
+
+The verifier checks the closed file set, metadata, source bridge hashes and all
+checksums. It validates and instantiates WebAssembly, checks ABI/engine/config
+identity, then executes native Unicode compile, bounded match and bounded
+substitution smoke cases plus normal and cap-stopped automatic-callout traces.
+
+The immutable signed-tag object is pinned. OpenPGP trust validation remains a
+release-operator step because the offline builder does not install or trust a
+key.
+
+## Runtime boundary
+
+ABI version 3 has no retained native handles. Each call compiles, obtains
+capture names, matches/substitutes or traces and releases its code, match data
+and match context before returning. The caller supplies fixed-capacity
+result/name/output/event/mark buffers. Hard maxima are 1 MiB pattern, 16 MiB
+subject, 1,000 captures, 10,000 matches, 100,000 capture rows, 50,000 trace
+events, 10 MiB serialized trace data and 128 MiB PCRE2 heap limit; the
+workbench uses stricter pattern and replacement input limits where applicable.
+
+PCRE2 always runs with UTF and UCP. Native UTF-8 byte offsets are retained in
+DTOs and converted only at valid code-point boundaries to half-open editor
+UTF-16 ranges. Lone UTF-16 surrogates are rejected before encoding.
+
+Normal execution lives only in `pcre2.worker`. Instrumented
+`PCRE2_AUTO_CALLOUT` collection is a separate ABI operation loaded only by
+`pcre2-trace.worker`; normal match, replacement, tests, corpus and benchmarks
+never call it. Each supervisor terminates its worker on timeout, crash,
+cancellation or supersession and lazily creates a clean generation for the
+next request.