# Ruby regular-expression engine

Regex Tools executes Ruby expressions in the actual CRuby 4.0.0 engine built
for `wasm32-wasi` by ruby.wasm. The reviewed runtime is the minimal
`ruby.wasm` from `@ruby/4.0-wasm-wasi@2.9.3-2.9.4`; the JavaScript host API is
`@ruby/wasm-wasi@2.9.3-2.9.4`.

The fixed `bridge.rb` module is evaluated once during worker start. Pattern,
flags, subject, limits and replacement travel through a bounded,
length-prefixed file in the worker-local WASI memory filesystem. Bounded inert
JSON returns metadata only; replacement output is written as UTF-8 to a
separate bounded worker-local file. No user-controlled value is evaluated or
interpolated as Ruby or JavaScript source, and the bridge does not use the
ruby.wasm `JS.eval` conversion path.

CRuby performs compilation and matching and reports character offsets, which
the adapter exposes as Unicode code-point native offsets and normalizes to
browser UTF-16 ranges. Native `String#gsub`/`String#sub` block iteration drives
replacement matching without materializing expanded output. A fixed streaming
implementation of CRuby 4.0.0's `rb_reg_regsub` grammar handles `\1` through
`\9`, `\k<name>`, `\0`, `\&`, ``\` ``, `\'`, `\+`, and `\\`; a load-time
bounded fixture verifies parity with CRuby. The expander stops on a valid UTF-8
boundary at the configured byte limit. Unpaired browser UTF-16 surrogates are
rejected before request encoding. A workbench timeout, cancellation,
supersession or crash terminates the dedicated worker and its complete
WebAssembly heap.

The deterministic pack contains only:

- `ruby.wasm`;
- `engine-metadata.json`;
- `SHA256SUMS`;
- ruby.wasm's exact `LICENSE.txt`;
- ruby.wasm's complete `NOTICE.txt`, including CRuby and bundled third-party
  notices; and
- the exact browser WASI shim and `tslib` license texts required by the
  JavaScript host bundle.