pbakaus_impeccable/docs/CUTOVER.md

Cutover: shipping the Rust engine (the maintainer's checklist)

State as of 2026-09-03. Everything below rust-swap is verified and pushed; nothing irreversible has happened: no engine tag, no npm publish, no merge. The detector is open source (the closed-core mechanism was built, measured, and removed the same week; the private impeccable-detector repo is archived as the record). The old impeccable-dist channel is archived too.

Steps, in order

1. Rebase and final drift check. git fetch && git log --oneline 94b7f34f..origin/main -- skill/scripts scripts/lib (nothing had landed as of 2026-09-03). Rebase rust-swap onto origin/main.
2. Engine release. bun run release:engine (clean tree, pushed, tag free, package.json platform pins equal ENGINE_VERSION). It tags engine-v<ENGINE_VERSION>; .github/workflows/release-engine.yml builds the five binaries (darwin-arm64, darwin-x64 on the arm64 runner, linux-x64 and linux-arm64 musl, windows-x64) and publishes them with .sha256 sidecars on this repo's Releases. Check: bun run check:engine-release passes its binary half.
3. npm. Create the @impeccable scope if it does not exist, npm login, then publish the five @impeccable/cli-<os>-<arch> platform packages from the release assets (cli/platform-packages/ holds the templates at version 0.0.0-engine; stamp ENGINE_VERSION, put the binary at bin/, npm publish --access public). Then the impeccable shim through bun run release:cli plus npm publish. bun run check:engine-release is fully green after this.
4. Clean-HOME launcher check. rm -rf ~/.impeccable/bin, then run skill/scripts/impeccable context from any project: it must download from engine-v<X> and run.
5. Merge rust-swap into main. The sync workflow regenerates the provider directories (they still carry copies of the retired JS engine; the sync rewrites them). CI's rust, rust-windows and oracle jobs are required already.
6. Version bumps and changelog for skill, CLI and extension. The extension is the wasm-core shell now (manifest held at 1.3.3; the bump plus a Web Store resubmission for the new offscreen permission are yours). Flip engine-release-ready to required.
7. Housekeeping. Revoke the fine-grained PAT impeccable-detector-release in your GitHub settings (created for the closed-core release flow; its secret is already deleted).

What to know

• cargo xtask bundle regenerates crates/live/assets/detect-antipatterns-browser.js (tracked) and extension/detector/ (vendored at build). bun run build:extension runs it; CI installs wasm-pack for that.
• The oracle replays byte-for-byte on macOS and Linux (795 cases on macOS, 794 plus one platform skip on Linux). tests/oracle/DELTAS.md records the two goldens re-recorded when the harness started staging workspaces at their real path.
• The Firefox extension zip is packaged and lint-clean but cannot run the offscreen-document design; a Gecko fallback is future work before an AMO release.
• Pristine consumes this engine as a wasm module built from a git revision pin (branch rust-engine in the pristine repo): its rules/ crate links impeccable-core, impeccable-wasm (detect feature) and impeccable-bundle with its own rule pack, and bun run engine:bump moves the pin (a weekly workflow opens the PR). No engine code is copied there. Until rust-swap merges, that pin points at a rust-swap commit; after the merge, switch the bump script's branch constant to main.