hcie-rust-v3.05/.kilo/plans/1784767806185-repair-failing-crates.md

Failing Crates Repair Plan

Goal

Make the bulk Linux and Windows test runners complete without platform-feature build failures, preserve compilation coverage for the existing egui visual examples, and report the exact names of failed crates instead of only a count.

Confirmed Findings

• hcie-blend fails because its eframe dev-dependency disables defaults without enabling either Linux backend; winit 0.30.13 therefore emits “platform ... not supported”.
• The same manifest defect exists in hcie-draw, hcie-filter, hcie-text, and hcie-vector.
• hcie-brush-engine succeeds because it enables x11; hcie-io enables both x11 and wayland.
• The root workspace already defines the intended cross-platform eframe configuration with wayland and x11.
• hcie-text/Cargo.toml currently repeats proptest and approx, which is a duplicate-key manifest error and must be fixed before any Cargo validation.
• The supplied terminal output proves one named failure (hcie-blend) and six failures in total. It does not expose all six names, so the prior six-name claim must not be treated as authoritative.
• run_all_tests.* and run_tests_categorized.* only retain failure counts. Their --no-4k command also places --skip on the Cargo side instead of after Cargo’s -- test-harness separator.

Implementation Steps

1. Restore a valid workspace manifest.

   • Remove the duplicate proptest and approx entries from hcie-text/Cargo.toml.
   • Run cargo metadata --no-deps immediately; stop if any other manifest error remains.

2. Centralize visual-example GUI dev-dependencies.

   • In hcie-blend, hcie-brush-engine, hcie-draw, hcie-filter, hcie-text, hcie-vector, and hcie-io, replace crate-local egui = "0.34" and custom eframe feature lists with egui = { workspace = true } and eframe = { workspace = true } under [dev-dependencies].
   • Preserve all non-GUI dev-dependencies and existing visual examples.
   • Do not add GUI dependencies to runtime [dependencies] and do not modify engine source files.
   • This intentionally reuses the root’s default_fonts, glow, persistence, wayland, and x11 configuration so platform support cannot drift between crates.

3. Verify feature resolution before compiling.

   • Use cargo tree -p <crate> -e features -i winit for the five confirmed failing crates and the two known-good comparison crates.
   • Confirm Linux builds activate at least one backend and the standardized configuration activates both winit/x11 and winit/wayland.

4. Improve test-runner diagnostics in both platform versions.

   • Update run_all_tests.sh, run_all_tests.bat, run_tests_categorized.sh, and run_tests_categorized.bat to append every failed crate name to a failure list and every skipped crate name to a skip list.
   • Print those lists in the final summary while preserving pass/fail/skip counts and non-zero exit status.
   • In shell scripts, use arrays for Cargo arguments rather than a space-split string.
   • Fix the 4K exclusion to invoke cargo test -p hcie-engine-api -- --skip benchmark_4k_stroke_on_multilayer_document; apply equivalent quoting and argument ordering in .bat files.
   • Keep default cargo test -p <crate> behavior so examples are compiled; do not hide the defect by globally switching to --tests.

5. Run focused crate validation.

   • Run cargo check -p <crate> --examples and cargo test -p <crate> for hcie-blend, hcie-draw, hcie-filter, hcie-text, and hcie-vector.
   • Re-run hcie-brush-engine and hcie-io to detect regressions from dependency centralization.
   • For hcie-io, distinguish build/test failures from missing external PSD fixtures; fixture-dependent early returns are not platform compilation failures.

6. Identify and repair the sixth failure from evidence.

   • Run the improved Linux bulk runner first with --no-io --no-4k for deterministic feedback.
   • Read the emitted failed-crate list. If a failure remains outside the five confirmed manifests, capture its first compiler/test error and fix that crate’s actual cause rather than assuming another winit defect.
   • Re-run only the remaining failed crate until green, then repeat the deterministic bulk run.

7. Complete end-to-end validation.

   • Run ./run_all_tests.sh --no-io --no-4k; require zero failed crates and verify the summary names no failures.
   • Run cargo test -p hcie-io separately with the expected fixture set or record fixture skips distinctly.
   • Run the 4K engine test explicitly with the protected command from AGENTS.md rather than silently omitting performance coverage.
   • Validate .bat parity on Windows (or Windows CI): targeted five-crate tests, run_all_tests.bat --no-io --no-4k, correct failed-name reporting, and non-zero exit code on an intentional failing command.

Risks And Guardrails

• Enabling x11/wayland compiles native backend support but does not launch windows during tests; headless execution remains safe because examples are only compiled.
• Do not use cached success as proof. At least one validation pass should use a fresh dedicated target directory (CARGO_TARGET_DIR=target/platform-test) rather than deleting the shared target directory.
• Do not alter locked engine logic or protected performance mechanisms; this repair is confined to manifests and test runners unless the newly identified sixth failure proves independent.
• Do not relocate the visual examples in this repair. Removing all GUI dev-dependencies from engine crates would require a separate architecture migration into the GUI workspace.
• The Linux environment cannot establish Windows batch correctness alone; Windows execution is a required validation gate, not an inferred result.

Acceptance Criteria

• cargo metadata --no-deps succeeds with no duplicate manifest keys.
• The five confirmed crates compile their examples and pass their tests on Linux.
• The bulk runner reports failed crate names and exits zero when all selected crates pass.
• ./run_all_tests.sh --no-io --no-4k reports zero failed crates from a fresh target directory.
• Windows .bat behavior matches Linux for argument handling, result lists, and exit status.
• Any sixth failure is named and resolved from its own diagnostic output, not from dependency-based speculation.