lda-ruby 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d0b97c33082528d2f992c4686e85e2080746938cd898c2a0662dd357979ad650
-  data.tar.gz: e4bd8e49f0b3f295b0f3ebfd78fc32db4835f24d93837ad566069b83046538c2
+  metadata.gz: a2470a73c1ba2c8807574f34a606a429adbd20d94457990667b59d241b521171
+  data.tar.gz: 8c7aa9b952901e15b48b974d68b339ab20e41edfcc07fa391266591b219b5771
 SHA512:
-  metadata.gz: cebd90cdaca9d030379105509325aac12f457eb9da75f8e2fc8f2d618d1ecbf201dc6b4407ec28e8f95b1dda4a71ba864b37ea16ad38a22b7605f2b7e281f908
-  data.tar.gz: fb452cc42435ff9382a39f878e8d7de5e3825e1b800e1cca4c2bec7684294d10fdec960f11cefc3f18a8c6381552e14ff058ecebd50884f91115d65e93880825
+  metadata.gz: 3fbe0fe85517e82b63bb8f28358178fd2490e1c4162342efa62864b7a5d83cc81488c83b75443bc8a539319717c588b37a27504722947c361a08636884ab4133
+  data.tar.gz: c240216720322fb4a539a63cff5c85a37544fbbad6281bb2b5c89787016f9dab817ab6db8295083e7c218454b23065ec06836e454b24d47e85111696e2e5dd1c

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+version 0.5.0
+=============
+
+- Expanded Rust-side EM orchestration with cached corpus snapshots, managed corpus sessions, and start-aware fallback paths.
+- Added Rust benchmark guardrails and deeper pure/Rust orchestration parity coverage.
+- Added release-blocking precompiled gem targets for Windows (`x64-mingw-ucrt`) and Linux musl (`x86_64-linux-musl`).
+- Hardened precompiled release workflows with full-matrix CI, post-publish verification, and release failure alerts.
+
 version 0.4.0
 =============
 

data/README.md

@@ -66,12 +66,15 @@ For an interactive shell with Rust toolchain + bindgen dependencies:
 - `bundle exec ruby -Ilib:test test/backend_compatibility_test.rb` runs backend compatibility fixtures.
 - `LDA_RUBY_BACKEND=rust bundle exec ruby -Ilib:test test/backend_compatibility_test.rb` runs parity checks in rust mode.
 - `./bin/benchmark-backends` benchmarks available backends (`pure`, `native`, `rust`) and prints JSON.
+- `./bin/check-rust-benchmark` enforces the Rust/pure benchmark ratio guardrail (configurable via env vars).
 - `./bin/docker-test-install-policies` verifies packaged-gem install behavior for `LDA_RUBY_RUST_BUILD=auto|always|never`, including runtime EM smoke checks.
 - `./bin/test-packaged-gem-fallback` verifies packaged-gem fallback behavior without Cargo (auto/never succeed, always fails) plus runtime smoke checks.
 - `./bin/test-packaged-gem-rust-enabled` verifies packaged-gem behavior with Cargo available (auto/always enable Rust, never disables Rust) plus runtime smoke checks.
 - `./bin/test-packaged-gem-manifest` verifies packaged-gem contents/metadata and rejects leaked build artifacts.
 - `./bin/release-preflight` runs unit tests + packaged-gem validation stack; set `SKIP_DOCKER=1` to skip Docker matrix checks.
 - `./bin/check-version-sync` verifies version parity between `VERSION.yml`, `lib/lda-ruby/version.rb`, and expected release tag.
+- `./bin/verify-rubygems-api-key` validates that your RubyGems API key can push non-interactively (required for CI release publishes).
+- `./bin/verify-release-publish --tag v0.4.0` verifies published RubyGems + GitHub release assets for a release tag.
 - `./bin/release-prepare 0.4.0` updates version/changelog files for a new release version.
 - `./bin/release-artifacts --tag v0.4.0` runs release checks, builds the source gem, and writes SHA256 checksums.
 - `./bin/release-precompiled-artifacts --tag v0.4.0 --platform x86_64-linux --skip-preflight` builds a precompiled platform gem and verifies install/runtime smoke checks.
@@ -123,7 +126,7 @@ For artifact strategy, compatibility targets, and rollout/deprecation rules, see
 
 `em("seeded")` is supported by both native and pure backends for deterministic fixture-oriented runs.
 
-Rust status: the extension hook layer is scaffolded in `ext/lda-ruby-rust`. Current Rust kernels include batched per-iteration corpus inference, batched per-document inference, topic-weights-per-word, topic-term-count accumulation, topic-term normalization/log-beta finalization, gamma-shift convergence reduction, topic-document average log-probability computation, and seeded topic-term initialization when `backend: :rust` is active; remaining model math still delegates to the pure Ruby backend. CI now runs dedicated rust-runtime checks and numeric parity fixtures against the pure backend.
+Rust status: the extension hook layer is scaffolded in `ext/lda-ruby-rust`. Current Rust kernels include batched per-iteration corpus inference, batched per-document inference, topic-weights-per-word, topic-term-count accumulation, topic-term normalization/log-beta finalization, gamma-shift convergence reduction, topic-document average log-probability computation, seeded topic-term initialization, random topic-term initialization, and Rust-side EM orchestration paths (`run_em`, `run_em_with_start`, `run_em_with_start_seed`, session-based `run_em_on_session_with_start_seed`, settings-aware session `run_em_on_session_start`, and unified session-settings orchestration `run_em_on_session`) when `backend: :rust` is active. Session orchestration now uses shared Rust-side corpus storage and borrowed execution paths so EM session runs do not deep-clone corpus arrays per call, and the Ruby adapter now auto-recreates missing Rust sessions before EM to stay on the session path. The Rust backend still keeps the pure Ruby implementation as a compatibility fallback path if Rust orchestration is unavailable or returns invalid output. CI runs dedicated rust-runtime checks and numeric parity fixtures against the pure backend.
 `compile_rust` and `LDA_RUBY_RUST_BUILD=always` require a Rust toolchain plus Ruby development headers and `libclang`.
 Gem packaging excludes local Rust build artifacts (`ext/lda-ruby-rust/target/**`) so local cargo outputs do not leak into published gems.
 

data/VERSION.yml

@@ -1,5 +1,5 @@
 ---
 :major: 0
-:minor: 4
+:minor: 5
 :patch: 0
 :build:

data/docs/modernization-handoff.md

@@ -4,22 +4,28 @@ This document is the canonical handoff state for continuing the Ruby 3.2+/3.3+ m
 
 ## Snapshot
 
-- Snapshot date: 2026-02-25
-- Active branch: `codex/modernization`
-- Branch head at snapshot: `7f9b101` (`Fix macOS Rust extension linking for precompiled builds`)
-- Repo status at snapshot: clean working tree on `codex/modernization` (in sync with `origin/codex/modernization`)
+- Snapshot date: 2026-03-02
+- Active branch: `codex/rust-orchestration-phase8`
+- Repo status at snapshot start: clean working tree on `codex/rust-orchestration-phase8` (ahead of `master`)
+- Modernization branch: `codex/modernization` merged into `master`
+- Merge commit for modernization PR: `bc11269` (`Merge pull request #18 from ealdent/codex/modernization`)
 - Latest release dry-run validation (GitHub Actions):
-  - date: 2026-02-25
-  - workflow run: `release.yml` run `22382692416` (`workflow_dispatch`, `publish=false`)
+  - date: 2026-03-02
+  - workflow run: `release.yml` run `22556487788` (`workflow_dispatch`, `publish=false`)
   - result: success (`validate release candidate`, `build release artifacts`, and all `build precompiled artifacts` matrix targets)
   - publish jobs skipped by design (`publish=false`)
-- Open pull request:
-  - `codex/modernization` -> `master`
+- Modernization pull request:
   - PR `#18`: `https://github.com/ealdent/lda-ruby/pull/18`
-- Latest PR CI validation (GitHub Actions):
-  - date: 2026-02-25
-  - workflow run: `CI` run `22383301379` (trigger: `pull_request` for PR `#18`)
-  - result: success (all checks green, including `precompiled gem build` matrix and install policy/rust runtime jobs)
+  - state: merged (2026-02-25)
+- Release publish attempts (`v0.4.0`):
+  - `release.yml` run `22383716372`: failed at RubyGems publish (`No such API key`)
+  - `release.yml` run `22383849236`: failed at RubyGems publish (`OTP code required`)
+  - rerun attempt (`22383849236`, attempt 2): failed at RubyGems publish (`OTP code required`)
+  - rerun attempt (`22383849236`, attempt 3): success (RubyGems publish + GitHub release publish complete)
+- Release status:
+  - `v0.4.0` published to RubyGems (source + precompiled Linux/macOS gems)
+  - GitHub release `v0.4.0` published with gem + `.sha256` assets
+  - next release dry-run matrix is validated for Linux, Linux musl, macOS Intel, macOS Apple Silicon, and Windows targets (`22556487788`)
 
 ## Project Goal
 
@@ -82,15 +88,28 @@ Delivered:
   - topic-document probability
   - seeded initialization
 - trusted kernel-output fast path enabled in rust mode
+- Rust-side EM orchestration path (`Lda::RustBackend.run_em`) retained as a compatibility fallback for precomputed beta-input execution
+- Rust-side start-aware deterministic orchestration path (`Lda::RustBackend.run_em_with_start`) for `seeded`/`deterministic` EM starts
+- Rust-side random-start orchestration path (`Lda::RustBackend.run_em_with_start_seed`) using explicit seed-controlled random initialization (`Lda::RustBackend.random_topic_term_probabilities`)
+- Rust-managed corpus session lifecycle (`Lda::RustBackend.create_corpus_session` / `drop_corpus_session`) with session-based start-aware EM orchestration (`run_em_on_session_with_start_seed`) wired in `Lda::Backends::Rust`
+- Rust-managed session settings lifecycle (`configure_corpus_session`) with settings-aware orchestration (`run_em_on_session_start`) wired in `Lda::Backends::Rust`
+- Rust session execution refactor to shared session corpus storage + borrowed orchestration helpers, eliminating deep corpus clone overhead on each session EM run
+- unified Rust session orchestration API (`run_em_on_session`) that applies settings + runs EM in one call inside Rust session orchestration
+- `Lda::Backends::Rust` now routes cached-corpus EM through managed Rust orchestration (`run_em_on_session_with_corpus`), leaving session reuse/recovery decisions in Rust and preferring that managed path even when no active session id is cached locally; when the managed API is unavailable it still prefers direct Rust non-session orchestration (`run_em_with_start_seed`) before legacy Ruby-side beta-input fallback (`run_em`)
+- direct non-session Rust orchestration now reuses the backend's cached Rust corpus snapshot instead of rebuilding corpus arrays from `@corpus` on each fallback invocation
+- legacy Rust beta-input compatibility fallback now also reuses the backend's cached Rust corpus snapshot, only asking the pure-Ruby backend to synthesize the initial beta matrix
+- Rust managed-session orchestration API (`run_em_on_session_with_corpus`) added to recreate missing sessions and run EM in one Rust call, and now directly falls back to start-aware array execution inside Rust if session-backed execution cannot be used
+- Rust session lifecycle replacement API (`replace_corpus_session`) added so corpus reassignment can update existing Rust sessions in place (config reset + corpus swap) instead of Ruby-side drop/recreate
+- `Lda::Backends::Rust` now keeps session-based orchestration on the managed Rust path (`run_em_on_session_with_corpus`) even when sessions are dropped externally
 - parity/compatibility test coverage and rust runtime CI
 
 Open in Phase 4:
 
-- optional deeper Rust ownership of orchestration logic (current design still intentionally delegates control flow through Ruby fallback scaffolding)
+- optional deeper Rust ownership beyond current unified session orchestration (for example additional control-plane logic and lifecycle APIs)
 
 ### Phase 5 (packaging/release)
 
-Status: Phase 5A complete (source-gem release automation), Phase 5B complete for initial Linux/macOS precompiled gems.
+Status: Phase 5A complete (source-gem release automation), Phase 5B complete for Linux/macOS/Windows/musl precompiled release matrix.
 
 Delivered:
 
@@ -101,25 +120,41 @@ Delivered:
 - packaged gem manifest/metadata gate (`bin/test-packaged-gem-manifest`)
 - single-command local gate (`bin/release-preflight`)
 - version/tag parity guard (`bin/check-version-sync`)
+- RubyGems CI credential preflight helper (`bin/verify-rubygems-api-key`)
+- post-publish artifact verification helper (`bin/verify-release-publish`)
 - deterministic release preparation helper (`bin/release-prepare`)
 - release artifact builder with checksum output (`bin/release-artifacts`)
 - precompiled artifact builder + runtime validator (`bin/release-precompiled-artifacts`)
 - gemspec precompiled variant support (`LDA_RUBY_GEM_VARIANT=precompiled`)
 - precompiled platform compatibility/publish policy (`docs/precompiled-platform-policy.md`)
+- precompiled target expansion tracker (`docs/precompiled-target-evaluation.md`)
 - macOS Rust build linker guardrail (`dynamic_lookup`) for precompiled packaging paths
 - tag-driven release workflow (`.github/workflows/release.yml`)
+- release failure alert workflow (`.github/workflows/release-failure-alert.yml`)
+  - tuned to create issues only for failed tag-triggered release runs, with failed job links in alert body
+  - now auto-closes matching alert issues when the same release run later reports success
 - maintainer release runbook (`docs/release-runbook.md`)
+- manual precompiled candidate workflow now validated on both lanes (`precompiled-candidate-evaluation.yml` run `22556129503`)
+- manual precompiled candidate workflow now validated with runtime checks on both lanes (`precompiled-candidate-evaluation.yml` run `22556206925`)
+- Windows candidate portability hardening across native + Rust build paths:
+  - C portability fixes (`cokus` macros, `time_t`, `_mkdir`)
+  - Rust toolchain alignment to GNU target for RubyInstaller (`x64-mingw-ucrt`)
+  - Rust bindgen header/sysroot compatibility wiring for Windows runners
+  - dual Rust DLL artifact-name staging support (`lda_ruby_rust.dll` and `liblda_ruby_rust.dll`)
 - CI jobs for packaged-gem fallback, rust-enabled checks, and manifest checks
-- CI precompiled gem build guardrail job (`precompiled-gem-build`)
+- CI precompiled gem build guardrail job (`precompiled-gem-build`) aligned to the full release-blocking precompiled matrix
+- macOS precompiled CI/release lanes now pin Homebrew `llvm@18` (with fallback to `llvm`) and export `LIBCLANG_PATH` from the selected prefix to avoid bindgen breakage from Homebrew LLVM drift
 - release workflow matrix for precompiled gems:
   - `x86_64-linux`
+  - `x86_64-linux-musl`
   - `x86_64-darwin`
   - `arm64-darwin`
+  - `x64-mingw-ucrt`
+- release dry-run validation for expanded precompiled matrix (`release.yml` run `22556487788`)
 
 Open in Phase 5:
 
-- optional expansion of precompiled targets (for example Windows and/or musl Linux)
-- tighter post-publish verification/alerting for multi-artifact release runs
+- optional expansion of precompiled targets beyond current Linux/macOS/Windows/musl set
 
 ## Validation Commands
 
@@ -131,6 +166,8 @@ Core:
 Packaging/release checks:
 
 - `./bin/check-version-sync`
+- `./bin/verify-rubygems-api-key`
+- `./bin/verify-release-publish --tag v0.4.0`
 - `./bin/test-packaged-gem-manifest`
 - `./bin/test-packaged-gem-fallback`
 - `./bin/test-packaged-gem-rust-enabled`
@@ -145,6 +182,9 @@ Optional full Docker matrix:
 Performance tracking:
 
 - `./bin/benchmark-backends`
+- `./bin/check-rust-benchmark`
+- `docs/rust-orchestration-guardrails.md`
+- CI currently enforces `BENCH_RUST_TO_PURE_MAX_RATIO=0.045` in `benchmark-guardrail`
 
 ## CI Jobs Expected
 
@@ -157,34 +197,37 @@ Performance tracking:
 - packaged gem manifest checks (`packaged-gem-manifest`)
 - precompiled gem build checks (`precompiled-gem-build`)
 - rust scaffold check (`rust-scaffold`)
+- benchmark guardrail check (`benchmark-guardrail`)
 - release validation/build/publish pipeline on `v*` tags (`release.yml`)
+- post-publish artifact verification (`verify_published_artifacts` in `release.yml`)
+- release-failure issue alerting (`release-failure-alert`)
 
 ## Remaining Work Queue
 
 Priority 1:
 
-- decide whether to keep current hybrid rust-kernel architecture or move more orchestration into Rust
-- if moving deeper into Rust, define parity guardrails and benchmark thresholds before refactors
+- continue periodic Rust-orchestration benchmark guardrail tightening (`docs/rust-orchestration-guardrails.md`) as performance data remains stable
+- keep hybrid backend compatibility guarantees (Rust + native + pure fallback) while extending Rust orchestration only behind parity/guardrail checks
 
 Priority 2:
 
-- evaluate additional precompiled targets (Windows and/or musl Linux)
-- add explicit post-publish verification checks for all uploaded release artifacts
+- monitor expanded precompiled release lanes (Windows + musl Linux) now that release dry-run matrix validation is green in run `22556487788`
+- evaluate any additional precompiled targets beyond current release-blocking set using `docs/precompiled-target-evaluation.md`
 
 Priority 3:
 
-- define automated alerts/notifications for release artifact publish failures
+- monitor release-failure auto-alert and auto-close behavior (`.github/workflows/release-failure-alert.yml`) and adjust signal/noise as release cadence grows
 
 ## Resume Instructions For A New Conversation
 
-1. Check out `codex/modernization`.
+1. Check out `master`.
 2. Open this file first: `docs/modernization-handoff.md`.
 3. Run `SKIP_DOCKER=1 ./bin/release-preflight`.
 4. Review `docs/release-runbook.md` for release flow/rollback details.
 5. Validate precompiled packaging locally for your host:
    - `./bin/release-precompiled-artifacts --tag "$(./bin/check-version-sync --print-tag)" --skip-preflight`
-6. Continue with `Priority 1` items under "Remaining Work Queue".
+6. Continue with remaining modernization queue (`Priority 1` then `Priority 2/3`).
 
 If you want the next assistant to continue immediately, use:
 
-"Open `docs/modernization-handoff.md`, validate with `SKIP_DOCKER=1 ./bin/release-preflight`, run `./bin/release-precompiled-artifacts --skip-preflight`, and continue the remaining modernization queue."
+"Open `docs/modernization-handoff.md`, validate with `SKIP_DOCKER=1 ./bin/release-preflight`, run `./bin/release-precompiled-artifacts --skip-preflight`, and continue the `Priority 1/2/3` modernization queue."

data/docs/porting-strategy.md

@@ -55,9 +55,25 @@ Completed in `codex/experiment-ruby3-modernization`:
 - Rust runtime CI job added (compile + execute rust backend tests).
 - Rust/Pure numeric parity fixtures added for deterministic seeded runs.
 - `compile_rust` now stages a Ruby-loadable extension artifact to avoid `Init_` symbol mismatch from Cargo's `lib*` output naming.
+- Rust-side EM orchestration path added (`Lda::RustBackend.run_em`) and retained as legacy compatibility fallback for precomputed beta-input execution.
+- Rust-side deterministic-start orchestration path added (`Lda::RustBackend.run_em_with_start`) so `seeded`/`deterministic` startup can stay in Rust.
+- Rust-side seed-controlled random-start orchestration path added (`Lda::RustBackend.run_em_with_start_seed` + `random_topic_term_probabilities`) so random initialization can stay in Rust while preserving deterministic replay from an explicit seed.
+- Rust-side corpus session lifecycle added (`create_corpus_session`/`drop_corpus_session`) and `Lda::Backends::Rust` now prefers session-based EM orchestration (`run_em_on_session_with_start_seed`) before array-based fallback paths.
+- Rust-side session settings lifecycle added (`configure_corpus_session`) and `Lda::Backends::Rust` now prefers settings-aware session orchestration (`run_em_on_session_start`) before parameter-heavy session and array-based fallbacks.
+- Rust session orchestration now runs on shared Rust-side corpus session data via borrowed execution helpers, avoiding deep corpus array cloning on each session EM call.
+- Unified Rust session API added (`run_em_on_session`) to apply settings and execute EM in one call inside Rust session orchestration.
+- `Lda::Backends::Rust` now prefers direct Rust non-session orchestration (`run_em_with_start_seed`) before legacy `run_em(initial_beta, ...)` compatibility fallback when a session path is unavailable.
+- Direct non-session Rust orchestration now reuses the backend's cached Rust corpus snapshot instead of rebuilding corpus arrays from `@corpus` on each fallback invocation.
+- Rust managed-session orchestration API added (`run_em_on_session_with_corpus`) to recreate missing sessions and execute EM in one Rust call.
+- Rust session lifecycle replacement API added (`replace_corpus_session`) so corpus reassignment can update existing Rust sessions in place (config reset + corpus swap) instead of Ruby-side drop/recreate.
+- `Lda::Backends::Rust` now routes cached-corpus EM through `run_em_on_session_with_corpus`, leaving session reuse/recovery decisions in Rust, preferring that managed path even when no active session id is cached locally, and reducing Ruby-side fallback branching when sessions are externally dropped.
+- `run_em_on_session_with_corpus` now acts as a unified Rust managed-corpus entrypoint: it attempts session-backed execution first, then falls back to direct start-aware array execution inside Rust when a managed session cannot be used.
+- Legacy `run_em(initial_beta, ...)` compatibility fallback now reuses the Rust backend's cached corpus snapshot and only relies on the pure-Ruby backend to synthesize the initial beta matrix.
 - Dockerized rust runtime workflow added for local parity with CI (`Dockerfile.rust`, `bin/docker-test-rust`).
 - Gem packaging now excludes local Rust cargo build artifacts (`target/**`) for clean release builds.
 - Backend benchmark driver added (`bin/benchmark-backends`) to track pure/native/rust runtime deltas.
+- Rust orchestration guardrail policy documented (`docs/rust-orchestration-guardrails.md`) with benchmark threshold checker (`bin/check-rust-benchmark`).
+- CI benchmark guardrail job added (`benchmark-guardrail`) to enforce Rust/pure runtime ratio on Ubuntu (currently `BENCH_RUST_TO_PURE_MAX_RATIO=0.045`).
 - Source install path now has explicit Rust build policy via `LDA_RUBY_RUST_BUILD=auto|always|never`.
 - Docker install-policy matrix script added (`bin/docker-test-install-policies`) to verify source install behavior across environments.
 - CI now runs install-policy matrix checks on Ubuntu.
@@ -71,7 +87,12 @@ Completed in `codex/experiment-ruby3-modernization`:
 - Release artifact helper added (`bin/release-artifacts`) to build source gem artifacts with SHA256 checksums.
 - Precompiled platform artifact helper added (`bin/release-precompiled-artifacts`) to build + validate native gems.
 - Tag-driven release workflow added (`.github/workflows/release.yml`) with dry-run support and environment-gated publish jobs.
-- CI precompiled guardrail job added (`precompiled-gem-build`) for Linux/macOS packaging checks.
+- RubyGems credential preflight helper added (`bin/verify-rubygems-api-key`) for CI-safe publish key validation.
+- Post-publish verification helper added (`bin/verify-release-publish`) to validate RubyGems + GitHub release artifacts by tag.
+- CI precompiled guardrail job added (`precompiled-gem-build`) for full release-blocking platform packaging checks (Linux, Linux musl, macOS Intel, macOS Apple Silicon, Windows).
+- macOS precompiled CI/release lanes now pin Homebrew `llvm@18` (with fallback to `llvm`) and export `LIBCLANG_PATH` from the selected prefix to avoid bindgen breakage from Homebrew LLVM drift.
+- Release workflow post-publish verification job added (`verify_published_artifacts`).
+- Release failure alert workflow added (`.github/workflows/release-failure-alert.yml`) to open issue alerts for failed tag-triggered `release.yml` runs and auto-close matching alerts when reruns succeed.
 - Maintainer release runbook added (`docs/release-runbook.md`) with publish and rollback/yank procedures.
 - Precompiled platform support policy added (`docs/precompiled-platform-policy.md`).
 
@@ -107,7 +128,7 @@ For an up-to-date resume snapshot (phase status + exact remaining queue), see `d
 
 - Phase 5A (source-gem release automation): complete.
 - Keep source build path available.
-- Phase 5B (precompiled/native gem publishing): complete for initial Linux/macOS targets via `bin/release-precompiled-artifacts` and release workflow matrix builds.
+- Phase 5B (precompiled/native gem publishing): complete for Linux/macOS/Windows/musl release matrix targets via `bin/release-precompiled-artifacts` and release workflow matrix builds.
 
 ## Tooling suggestions
 

data/docs/precompiled-platform-policy.md

@@ -11,6 +11,8 @@ Each release version publishes a split package set:
   - `lda-ruby-<version>-x86_64-linux.gem`
   - `lda-ruby-<version>-x86_64-darwin.gem`
   - `lda-ruby-<version>-arm64-darwin.gem`
+  - `lda-ruby-<version>-x64-mingw-ucrt.gem`
+  - `lda-ruby-<version>-x86_64-linux-musl.gem`
 
 The source gem remains the universal fallback. Platform gems are additive and are expected to install without local build tools.
 Precompiled artifacts are built on matching host runners (no cross-compilation in current workflow).
@@ -20,8 +22,10 @@ Precompiled artifacts are built on matching host runners (no cross-compilation i
 - Supported Ruby versions: 3.2 and 3.3 (plus future versions validated by CI).
 - Release-blocking precompiled targets:
   - Linux `x86_64-linux`
+  - Linux musl `x86_64-linux-musl`
   - macOS Intel `x86_64-darwin`
   - macOS Apple Silicon `arm64-darwin`
+  - Windows `x64-mingw-ucrt`
 - Other platforms:
   - Install from source gem.
   - Runtime remains supported through native/pure fallback paths.
@@ -47,10 +51,18 @@ Release automation requirements:
 - `.github/workflows/release.yml` builds source + precompiled artifacts.
 - Release workflow matrix must include all release-blocking precompiled targets.
 - Publish jobs push all built gems and attach checksums to GitHub releases.
+- Post-publish verification job must validate RubyGems entries and GitHub release assets for the tagged version.
 
 Continuous integration guardrail:
 
-- `.github/workflows/ci.yml` runs `release-precompiled-artifacts` for representative Linux/macOS targets on every branch/PR.
+- `.github/workflows/ci.yml` runs `release-precompiled-artifacts` for the full release-blocking precompiled matrix (Linux, Linux musl, macOS Intel, macOS Apple Silicon, Windows) on every branch/PR.
+- macOS precompiled lanes pin Homebrew `llvm@18` (falling back to `llvm` if unavailable) and export `LIBCLANG_PATH` from the selected prefix to keep bindgen stable across Homebrew formula updates.
+- `.github/workflows/precompiled-candidate-evaluation.yml` is used for additional platform candidate checks.
+- `.github/workflows/release.yml` dry-run validates the full release-blocking matrix before publish.
+
+Latest release-matrix validation:
+
+- [release dry-run 22556487788](https://github.com/ealdent/lda-ruby/actions/runs/22556487788) succeeded for Linux, Linux musl, macOS Intel, macOS Apple Silicon, and Windows targets.
 
 ## Rollout / Expansion Rules
 
@@ -59,7 +71,8 @@ When adding a new precompiled platform:
 1. Add target to release workflow matrix.
 2. Add or update CI coverage for that platform family.
 3. Update this policy and the release runbook support matrix.
-4. Validate a dry-run release with `workflow_dispatch` before shipping.
+4. Record feasibility evidence and rollout notes in `docs/precompiled-target-evaluation.md`.
+5. Validate a dry-run release with `workflow_dispatch` before shipping.
 
 When deprecating a precompiled platform:
 

data/docs/precompiled-target-evaluation.md

@@ -0,0 +1,67 @@
+# Precompiled Target Evaluation (Priority 2)
+
+This document tracks current feasibility for expanding precompiled gem targets beyond the Phase 5B baseline.
+
+Current release-blocking precompiled targets:
+
+- `x86_64-linux`
+- `x86_64-darwin`
+- `arm64-darwin`
+- `x64-mingw-ucrt`
+- `x86_64-linux-musl`
+
+Reference implementation constraints:
+
+- `bin/release-precompiled-artifacts` only supports host-matching platform builds (no cross-compilation).
+- Release workflow currently uses matching host runners for each precompiled target.
+
+## Candidate: Windows (`x64-mingw-ucrt`)
+
+Status: promoted to release-blocking after release dry-run matrix success.
+
+Feasibility notes:
+
+- GitHub Actions provides Windows runners, so host-matching builds are possible in principle.
+- Existing release tooling is bash-first and assumes POSIX shell ergonomics throughout.
+- Runtime smoke and packaged-gem checks were validated in candidate runs before promotion.
+- Candidate runs:
+  - [run 22555475302](https://github.com/ealdent/lda-ruby/actions/runs/22555475302): failed in native extension compile (`rake compile`) with `cokus.h` macro collision and `time_t` mismatch.
+  - [run 22555550326](https://github.com/ealdent/lda-ruby/actions/runs/22555550326): progressed further, failed on `utils.c` `mkdir(name, mode)` mismatch (Windows `_mkdir` required).
+  - [run 22556009214](https://github.com/ealdent/lda-ruby/actions/runs/22556009214): Rust bindgen/toolchain parsing fixed; build then failed on Windows DLL name staging expectation.
+  - [run 22556129503](https://github.com/ealdent/lda-ruby/actions/runs/22556129503): Windows candidate build + artifact upload succeeded after GNU toolchain alignment, bindgen header/sysroot setup, and dual DLL name staging support.
+  - [run 22556206925](https://github.com/ealdent/lda-ruby/actions/runs/22556206925): Windows candidate remained green with packaged-gem runtime smoke checks enabled.
+  - [run 22556487788](https://github.com/ealdent/lda-ruby/actions/runs/22556487788): release workflow dry-run succeeded with `windows-x64-mingw-ucrt` included in release matrix.
+
+Required validation to promote:
+
+1. Completed: release dry-run matrix validation passed.
+
+## Candidate: musl Linux (`x86_64-linux-musl`)
+
+Status: promoted to release-blocking after release dry-run matrix success.
+
+Feasibility notes:
+
+- Current workflow uses `ubuntu-latest` (glibc), not musl.
+- Current artifact script rejects cross-platform builds, so a musl artifact requires either:
+  - a musl-hosted builder, or
+  - a dedicated musl-native build container/workflow path treated as host-equivalent for packaging.
+- Local validation signal (2026-03-01): Alpine container dry-run succeeded for host-matching `aarch64-linux-musl` with:
+  - `./bin/release-precompiled-artifacts --platform <detected-musl-platform> --skip-preflight --skip-runtime-checks`
+- Candidate workflow runs (2026-03-01):
+  - [run 22555475302](https://github.com/ealdent/lda-ruby/actions/runs/22555475302): built `x86_64-linux-musl` successfully but artifact upload path was misconfigured.
+  - [run 22555550326](https://github.com/ealdent/lda-ruby/actions/runs/22555550326): musl candidate built and uploaded artifacts successfully with corrected glob path (`pkg/lda-ruby-*-linux-musl.gem*`).
+  - [run 22556129503](https://github.com/ealdent/lda-ruby/actions/runs/22556129503): musl candidate build + artifact upload remained green alongside the fixed Windows lane.
+  - [run 22556206925](https://github.com/ealdent/lda-ruby/actions/runs/22556206925): musl candidate remained green with packaged-gem runtime smoke checks enabled.
+  - [run 22556487788](https://github.com/ealdent/lda-ruby/actions/runs/22556487788): release workflow dry-run succeeded with `linux-musl-x86_64` included in release matrix.
+
+Required validation to promote:
+
+1. Completed: release dry-run matrix validation passed.
+
+## Recommendation
+
+Current expansion step is complete for Windows and musl. Any additional target should follow the same sequence:
+1. Add candidate workflow coverage.
+2. Verify candidate runtime checks.
+3. Validate one release dry-run with the new matrix lane before promotion.

data/docs/release-runbook.md

@@ -2,7 +2,7 @@
 
 This runbook defines the maintainer workflow for shipping `lda-ruby` source and precompiled platform gem releases.
 
-Authoritative platform/support policy is maintained in `docs/precompiled-platform-policy.md`.
+Authoritative platform/support policy is maintained in `docs/precompiled-platform-policy.md`; expansion feasibility notes live in `docs/precompiled-target-evaluation.md`.
 
 ## Scope
 
@@ -34,7 +34,7 @@ Authoritative platform/support policy is maintained in `docs/precompiled-platfor
 
 GitHub repository secret:
 
-- `RUBYGEMS_API_KEY`: API key with push rights for `lda-ruby`.
+- `RUBYGEMS_API_KEY`: API key with push rights for `lda-ruby` and non-interactive publish support (no OTP prompt during `gem push`).
 
 GitHub Actions environment:
 
@@ -69,7 +69,15 @@ GitHub Actions environment:
 
    Note: `release-precompiled-artifacts` only supports building for the current host platform (no cross-compilation).
 
-5. Commit and merge to `master`.
+5. Verify RubyGems API key behavior before tagging:
+
+   ```bash
+   ./bin/verify-rubygems-api-key
+   ```
+
+   This check intentionally attempts a duplicate push of an existing gem version. A duplicate-rejected response is expected and confirms non-interactive auth works.
+
+6. Commit and merge to `master`.
 
 ## Dry-Run Path (No Publish)
 
@@ -84,10 +92,16 @@ Behavior:
 
 Latest verified dry-run reference:
 
-- date: 2026-02-25
-- workflow run: `https://github.com/ealdent/lda-ruby/actions/runs/22382692416`
+- date: 2026-03-02
+- workflow run: `https://github.com/ealdent/lda-ruby/actions/runs/22556487788`
 - dispatch parameters: `release_tag=v0.4.0`, `publish=false`
 - result: success across `validate`, `build_artifacts`, and full `build_precompiled_artifacts` matrix
+  - verified precompiled lanes:
+    - `linux-x86_64`
+    - `linux-musl-x86_64`
+    - `macos-x86_64`
+    - `macos-arm64`
+    - `windows-x64-mingw-ucrt`
 
 Optional local dry-run equivalent:
 
@@ -96,6 +110,21 @@ Optional local dry-run equivalent:
 ./bin/release-precompiled-artifacts --tag v0.4.0 --skip-preflight
 ```
 
+Candidate expansion workflow:
+
+- For future platform evaluation beyond current release-blocking targets, run `.github/workflows/precompiled-candidate-evaluation.yml` via `workflow_dispatch`.
+- Record outcome artifacts/logs in `docs/precompiled-target-evaluation.md`.
+
+## Known Publish Incident (`v0.4.0`)
+
+- date: 2026-02-25
+- release runs:
+  - `https://github.com/ealdent/lda-ruby/actions/runs/22383716372`
+  - `https://github.com/ealdent/lda-ruby/actions/runs/22383849236` (attempt 1 + rerun attempt 2 + rerun attempt 3)
+- result: artifact build stages passed, `publish to RubyGems` failed with OTP-required auth (`You have enabled multifactor authentication but no OTP code provided.`)
+- recovery action: rotated `release` environment secret `RUBYGEMS_API_KEY` to a CI-safe key and reran run `22383849236`.
+- recovery result: rerun attempt 3 succeeded; RubyGems `0.4.0` and GitHub release `v0.4.0` published.
+
 ## Publish Path (Tag-Driven)
 
 1. Ensure the release commit is on `master`.
@@ -111,13 +140,17 @@ Optional local dry-run equivalent:
 3. Monitor `.github/workflows/release.yml`:
    - `validate`
    - `build_artifacts`
-   - `build_precompiled_artifacts` (linux + macOS matrix)
+   - `build_precompiled_artifacts` (linux + linux-musl + macOS + windows matrix)
    - environment-gated `publish_rubygems`
    - environment-gated `publish_github_release`
+   - `verify_published_artifacts`
+   - on failed tag-triggered `release.yml` runs, `.github/workflows/release-failure-alert.yml` opens a triage issue with failed job links
+   - if the same release run later succeeds (for example via rerun), the alert issue is auto-closed by `.github/workflows/release-failure-alert.yml`
 4. Approve the protected `release` environment when prompted.
 5. Confirm published outputs:
    - RubyGems shows `lda-ruby` `0.4.0` source gem and platform gems
    - GitHub release `v0.4.0` exists with all gem and `.sha256` attachments
+   - workflow job `verify_published_artifacts` succeeds
 
 ## Rollback and Recovery
 
@@ -151,6 +184,8 @@ If an incorrect gem is published:
 - `cargo not found` in rust-enabled checks: ensure Rust toolchain is installed or run in Docker.
 - `libclang` not found while building precompiled gems: install LLVM/libclang and set `LIBCLANG_PATH` if needed.
 - Linux `Install Rust bindgen dependencies` can take several minutes on fresh runners due apt package index and package installs.
+- RubyGems publish asks for OTP (`You have enabled multi-factor authentication but no OTP code provided`): run `./bin/verify-rubygems-api-key`, then rotate `RUBYGEMS_API_KEY` to a CI-safe key if OTP is requested.
+- Post-publish verification fails: run `./bin/verify-release-publish --tag vX.Y.Z` and fix missing RubyGems entries or GitHub release assets before considering the release complete.
 - macOS Rust link errors (`symbol(s) not found` for Ruby APIs): ensure build path preserves `-C link-arg=-Wl,-undefined,dynamic_lookup` in `RUSTFLAGS`.
 - Tag/version mismatch: run `./bin/check-version-sync --tag vX.Y.Z`.
 - Artifact mismatch during release: rebuild with `./bin/release-artifacts --tag vX.Y.Z`.

data/docs/rust-orchestration-guardrails.md

@@ -0,0 +1,50 @@
+# Rust Orchestration Guardrails
+
+This document defines the minimum parity and performance gates for deeper Rust orchestration refactors.
+
+## Numeric parity guardrails
+
+Required tests:
+
+- `bundle exec ruby -Ilib:test test/backend_compatibility_test.rb`
+- `bundle exec ruby -Ilib:test test/rust_orchestration_test.rb`
+
+Current parity expectations:
+
+- Rust vs pure backend fixture parity remains exact within existing tolerances used by tests.
+- Session-based orchestration paths (`run_em_on_session`, `run_em_on_session_with_start_seed`, `run_em_on_session_start`, `run_em_on_session_with_corpus`) must match direct non-session orchestration for equivalent settings/seeds.
+- `Lda::Backends::Rust` cached-corpus EM should prefer the managed Rust session entrypoint (`run_em_on_session_with_corpus`) even when no active session id is cached locally, rather than branching in Ruby between session-only, recovery, and direct paths.
+- `Lda::Backends::Rust` non-session fallback should prefer Rust start-aware orchestration (`run_em_with_start_seed`) before legacy beta-input orchestration (`run_em`).
+- Direct non-session fallback should reuse the backend's cached Rust corpus snapshot rather than rebuilding corpus arrays from `@corpus` for each invocation.
+- Legacy beta-input compatibility fallback should also reuse the backend's cached Rust corpus snapshot rather than rebuilding full EM corpus input in Ruby.
+- Rust backend corpus/session lifecycle must not leak session count across corpus replacement.
+- Missing-session recovery in managed session orchestration (`run_em_on_session_with_corpus`) must recreate a usable session and keep parity with direct orchestration.
+- Managed Rust corpus orchestration (`run_em_on_session_with_corpus`) must keep parity with direct orchestration even when it falls back internally from session-backed execution to start-seeded array execution.
+- Corpus reassignment through Rust session replacement lifecycle (`replace_corpus_session`) must preserve stable session count and route subsequent EM runs over updated corpus data.
+- Unknown start-mode handling in seed-aware Rust orchestration must match Ruby's non-seeded fallback behavior when given the same explicit seed.
+
+## Benchmark guardrail
+
+Run:
+
+- `./bin/check-rust-benchmark`
+
+Default benchmark policy:
+
+- `BENCH_RUST_TO_PURE_MAX_RATIO=0.045`
+  - i.e., Rust mean runtime must be no worse than 4.5% of pure mean runtime on the benchmark fixture/config.
+- CI benchmark guardrail job enforces the same ratio with `BENCH_RUNS=1` for runtime stability.
+- latest tightening evidence (2026-03-05): local Docker guardrail check with `BENCH_RUNS=3` observed Rust/Pure ratio `0.0368` (`rust=0.0758s`, `pure=2.0569s`), and prior CI streak data on `codex/rust-orchestration-phase8` (`22555725309` .. `22557953998`) observed `[0.0252, 0.0288]`, supporting a tighter `0.045` threshold with headroom.
+
+Configurable environment knobs:
+
+- `BENCH_RUNS` (default `5`)
+- `BENCH_START` (default `seeded`)
+- `BENCH_TOPICS` (default `8`)
+- `BENCH_MAX_ITER` (default `20`)
+- `BENCH_EM_MAX_ITER` (default `40`)
+- `BENCH_RUST_TO_PURE_MAX_RATIO` (default `0.045`)
+
+## When to tighten thresholds
+
+Tighten benchmark thresholds only after collecting multiple stable runs on the same host/environment and updating this document with the new target ratio.

data/ext/lda-ruby/cokus.c

@@ -45,14 +45,14 @@
 
 #include "cokus.h"
 
-static uint32   state[N+1];     // state vector + 1 extra to not violate ANSI C
+static uint32   state[COKUS_N+1];     // state vector + 1 extra to not violate ANSI C
 static uint32   *next;          // next random value is computed from here
 static int      left = -1;      // can *next++ this many times before reloading
 
 void seedMT(uint32 seed)
  {
     //
-    // We initialize state[0..(N-1)] via the generator
+    // We initialize state[0..(COKUS_N-1)] via the generator
     //
     //   x_new = (69069 * x_old) mod 2^32
     //
@@ -100,28 +100,28 @@ void seedMT(uint32 seed)
     register uint32 x = (seed | 1U) & 0xFFFFFFFFU, *s = state;
     register int    j;
 
-    for(left=0, *s++=x, j=N; --j;
+    for(left=0, *s++=x, j=COKUS_N; --j;
         *s++ = (x*=69069U) & 0xFFFFFFFFU);
  }
 
 
 uint32 reloadMT(void)
 {
-    register uint32 *p0=state, *p2=state+2, *pM=state+M, s0, s1;
+    register uint32 *p0=state, *p2=state+2, *pM=state+COKUS_M, s0, s1;
     register int    j;
 
     if(left < -1)
         seedMT(4357U);
 
-    left=N-1, next=state+1;
+    left=COKUS_N-1, next=state+1;
 
-    for(s0=state[0], s1=state[1], j=N-M+1; --j; s0=s1, s1=*p2++)
-        *p0++ = *pM++ ^ (mixBits(s0, s1) >> 1) ^ (loBit(s1) ? K : 0U);
+    for(s0=state[0], s1=state[1], j=COKUS_N-COKUS_M+1; --j; s0=s1, s1=*p2++)
+        *p0++ = *pM++ ^ (mixBits(s0, s1) >> 1) ^ (loBit(s1) ? COKUS_K : 0U);
 
-    for(pM=state, j=M; --j; s0=s1, s1=*p2++)
-        *p0++ = *pM++ ^ (mixBits(s0, s1) >> 1) ^ (loBit(s1) ? K : 0U);
+    for(pM=state, j=COKUS_M; --j; s0=s1, s1=*p2++)
+        *p0++ = *pM++ ^ (mixBits(s0, s1) >> 1) ^ (loBit(s1) ? COKUS_K : 0U);
 
-    s1=state[0], *p0 = *pM ^ (mixBits(s0, s1) >> 1) ^ (loBit(s1) ? K : 0U);
+    s1=state[0], *p0 = *pM ^ (mixBits(s0, s1) >> 1) ^ (loBit(s1) ? COKUS_K : 0U);
     s1 ^= (s1 >> 11);
     s1 ^= (s1 <<  7) & 0x9D2C5680U;
     s1 ^= (s1 << 15) & 0xEFC60000U;
@@ -142,4 +142,3 @@ uint32 randomMT(void)
     y ^= (y >> 18);
     return(y);
  }
-