# Ruby grammar: pinned build and compatibility verification

**Reassessed requirements:** [Proportionate release assessment](sonicweb-proportionate-release-assessment.md) supersedes blanket rebuild/grammar/legal-review gates below. No required engine source file is currently identified as missing from the prepared bundle. MIT self-compilation and distributor toolchain rebuilds are not mandatory license conditions. Conditional GO for controlled staging after owner approval/exact HTTPS configuration; upload prohibition and genuine source/security protections remain.

The installed grammar remains unchanged. A fresh source build was **not** performed: Emscripten, Docker and the tree-sitter CLI are absent on this machine. Node 24, npm, pnpm, Cargo and host Clang are present; host Clang alone is not the Emscripten dynamic-WASM toolchain. The user's approved fallback is prepared below. Publication quarantine remains active.

## Public inputs and notices

- Grammar: `tree-sitter-ruby@0.20.1`, npm gitHead [`7a010836b74351855148818d5cb8170dc4df8e6a`](https://github.com/tree-sitter/tree-sitter-ruby/tree/7a010836b74351855148818d5cb8170dc4df8e6a).
- Official source archive: [ruby-0.20.1.tgz](https://registry.npmjs.org/tree-sitter-ruby/-/tree-sitter-ruby-0.20.1.tgz). SHA-256 `698d408518ddb6163600a789eb878483487d7830faa8e0da7386cf7937747f88`; the prior investigation checked npm integrity. The archive contains generated parser C, external scanner C, parser headers, grammar source and MIT license.
- MIT copyright: **2016 Rob Rix**. Full upstream text is preserved in `legal/grammar-build-ruby-MIT.txt`; the existing distribution notice must remain.
- Build baseline: [wrapper workflow at `3e88dc9…`](https://github.com/Gregoor/tree-sitter-wasms/blob/3e88dc9e36b4e8bf752ce53bea61e4b67282a2bb/.github/workflows/build-and-publish.yml), Emscripten **2.0.24**, tree-sitter CLI **0.20.8** from its lockfile. The wrapper's Node 20 installation/pnpm packaging steps are unnecessary for the offline build driver after the CLI is installed. Do not use SuperSonic's Emscripten 4.0.21.
- `legal/grammar-build-inputs.json` records archive and parser/scanner/header/grammar/license hashes. The script does not download or execute remote installers.

## Proposed isolated/CI procedure — not executed

Use a disposable Linux build environment, separate from the portfolio checkout. No deployment secrets, repository write token or upload stage. Prepare and review tooling in a network-enabled setup step, then disable networking for compilation. Supply Bash, tar, shasum/coreutils, Emscripten 2.0.24 with its matching LLVM/Binaryen/Python/Node, and tree-sitter CLI 0.20.8. The CLI npm package is a downloader wrapper; do not mistake it for a self-contained compiler. If downloading the CLI release binary, record its exact URL and SHA-256; alternatively build the CLI 0.20.8 source with a pinned Rust toolchain and retain the complete Cargo lock/source inputs. Review all compiler installers before execution.

For a genuinely repeatable build, pin the container **digest**, CLI binary hash, OS packages and setup scripts; save those alongside build logs. No image digest or CLI executable identity has been verified here, so this is a version-pinned recipe, not a demonstrated reproducible or bit-identical build. Never use an unpinned `latest` image or an automatic network installer as if verified.

Once that reviewed environment is available, copy the verified Ruby source tarball and this driver into it:

```sh
bash scripts/grammar-build-isolated.sh /inputs/ruby-0.20.1.tgz /output/ruby-build-1
```

The driver verifies source SHA-256 and tool versions, extracts into a new directory, runs `tree-sitter build-wasm` on the shipped generated C without regeneration, and retains source, full MIT license, build log and candidate hash. It never writes the active grammar. Run a second build in a clean environment with identical pinned inputs; compare the WASM hashes. A differing hash requires investigation, while matching hashes establish repeatability only for those recorded inputs.

Copy the candidate to an ignored local directory, then from `prototypes/sonicweb-local`:

```sh
npm run build:restricted
node scripts/grammar-build-compare.mjs /absolute/path/to/candidate/tree-sitter-ruby.wasm
npm test
```

The comparison uses the existing `web-tree-sitter@0.24.7`, verifies parser loading, absence of parse errors, exact syntax-tree shape and restricted-program equality for original and annotated compositions, then compares full 240-second virtual interpreter traces for seeds 0, 1, 42 and 999 with the approved independent random table. Sample durations are fixtures; this is parser/interpreter verification, not audible playback. The normal suite uses the currently installed binary; candidate comparison explicitly loads the new candidate. After success, use a separate local candidate-runtime export and browser tests before any adoption. Do not silently overwrite node_modules, active grammar or source music.

## Results actually executed

- Source archive re-read locally; parser/scanner/header/grammar/license SHA-256 values recorded. License file copied byte-for-byte.
- `bash -n scripts/grammar-build-isolated.sh`: passed (syntax only; not compilation).
- ESLint for `scripts/grammar-build-compare.mjs`: passed.
- Invalid source archive negative test: rejected at checksum verification before extraction/tool execution; no output directory created.
- Compatibility harness run against the **existing published binary**, SHA-256 `93a5022855314cdb45458c7bb026a24a0ebc3a5ff6439e542e881f14dfa13a39`: passed both files, four seeds and **43,842 compared events**. Evidence: ignored `static-build/provenance-research/grammar-current-compatibility.json`. This validates the harness and baseline; it does **not** prove a source-built grammar works or establish published binary lineage.

Remaining technical gate: provision the reviewed isolated toolchain, compile twice, record all inputs, compare the actual candidate with the current runtime, run candidate browser regressions and package its source/license/build evidence. MIT does not inherently require maintainer contact or special permission. No upstream contact is proposed.