---
id: SMH-PLAN-YDTABECL
type: plan
title: "Dependency Freshness and Compatible Resolution"
spec: SMH-SPEC-SPEC0001
status: approved
---

# Dependency Freshness and Compatible Resolution

## Intent

Keep Smith dependencies current without confusing app reproducibility with downstream library compatibility.
Upgrade workspace dependencies to the latest stable releases that satisfy Smith's contracts and gates.

## Scope and coordination

Existing foundation work supplies Cargo automation and audit gates.
Release Readiness owns public Rust SemVer checking and release packaging; this plan does not duplicate those tasks.
JSON Boundaries identifies audit and instruction-budget blockers; this plan handles dependency upgrades, not its implementation or board state.
Plugin deprecation tooling and historical stable-world hosting are deferred to their operating epochs.
Current prototype upgrades verify real guest consumers without claiming permanent plugin compatibility.

## Entry

Read current manifest requirements, resolved graphs, toolchain, audit policy, and CI automation.
Run fresh audit before choosing upgrade targets; earlier vulnerability and yank reports are historical evidence, not current verdicts.
Inventory production, development, build, and guest dependencies, including target-specific edges.

## Constraints

- Cargo remains the only automation interface; reuse xtask and Luci CI.
- Protected manifests, toolchain, and configuration files require explicit approval for proposed changes.
- Ordinary builds stay locked; resolution verification explicitly creates separate candidate lockfiles and then runs locked gates.
- Candidate manifests, lockfiles, and experimental artifacts live in approved OS temporary space; obtain permission before creating that scratch workspace.
- Existing checkout lockfile and user changes remain intact during candidate verification.
- Library defaults permit SemVer-compatible resolution; minimums reflect required APIs, correctness, or security, not merely latest available versions.
- Narrow requirements retain a concrete reason; inspect existing exact and tilde constraints individually.
- Host engine, guest bindings, and shared Wasm tooling are evaluated as a coordinated release set.
- Upgrades and instruction-budget re-pins are separate deliberate commits; no automatic merging, blanket warning exemptions, or suppressed audit findings.

## Vertical slices

### 1. Observable dependency freshness

Expose a Cargo-owned report distinguishing required range, locked version, latest compatible release, latest stable release, and constraint reason.
Include direct workspace dependencies across production, dev, build, target, and guest scopes; retain existing lockfile-wide security and yank reporting for transitive dependencies.
Report unavailable registry evidence as an error or explicitly incomplete result, never as up-to-date.
Prove classification with deterministic fixtures and the actual Cargo command before integrating scheduled CI execution.
The schedule publishes reviewable findings without modifying dependencies; document its cadence and how humans obtain the latest report.

### 2. Security and coordinated Wasm upgrade

Use fresh audit results to select patched, non-yanked releases.
Review the previously reported Wasmtime and yoke-derive findings first if still present.
Present required protected-file edits for approval, then make the smallest coherent upgrade.
Verify real guest build, host loading, sandbox rejection boundaries, and a binary workflow before proceeding.
Run fresh audit and applicable quality gates; leave a working dependency graph after this slice.

### 3. Latest compatible workspace stack

Review all remaining direct dependencies, including dev tooling used by tests and benchmarks.
Evaluate newer breaking lines rather than stopping at what current ranges admit.
Keep justified unstable-API constraints; remove unjustified restrictions when consumer verification succeeds.
Migrate one coherent dependency concern at a time through its public or user-facing consumer, with regression coverage before required code changes.
Verify each migration before starting the next; never batch unrelated upgrades behind one final test run.
Record every retained older release with its concrete blocker; unresolved blockers prevent claiming the latest-working inventory complete.

### 4. Downstream resolution guarantees

Expose Cargo-owned verification for the committed graph, freshly resolved compatible graph, and declared direct-dependency minimums.
Verify library consumers outside workspace resolution, including supported default configurations and target-specific edges.
Exercise coordinated guest tooling separately from host library resolution.
Distinguish registry/tooling failure from a dependency incompatibility.
Pin a too-low minimum regression and show that verification rejects it before correcting the requirement.
Keep all ordinary build steps locked against the selected graph and prove candidate checks cannot rewrite the checkout lockfile.
Integrate these checks into release verification without duplicating Release Readiness's Rust API-diff gate.

### 5. Verified closeout

Re-run dependency freshness, resolution verification, check, E2E, documentation, architecture, audit, and guest build/load gates on the final graph.
Run instruction budgets through the pinned CI-image workflow; review changed counts and deliberately re-pin only supported measurements in a separate commit.
Read complete results; report any registry, target, tooling, or compatibility gap as a blocker.

## Verification matrix

| Behavior | Evidence |
| --- | --- |
| Compatible and breaking updates visible | Deterministic classification fixtures plus actual Cargo report and scheduled CI output. |
| Narrow constraints justified | Per-dependency reason and verified consumer behavior. |
| Latest working release set | Final inventory has no unexplained newer stable direct dependency; rejected candidates have concrete evidence. |
| Security boundary retained | Fresh audit, sandbox rejection tests, guest load, real-binary workflow. |
| Library requirements honest | Committed, fresh-compatible, and minimum-resolution consumer checks pass. |
| Reproducibility preserved | Candidate checks leave checkout lockfile unchanged; final builds run locked. |
| Performance gates preserved | Pinned-platform results reviewed; any re-pin is explicit and independently committed. |

## Execution evidence

Verified on Linux x86_64 with stable Rust 1.99.0.

- Dependency change: `nvlqlnnw`; separate instruction-budget change: `ytvlqkrr`.
- Pre-existing workspace work preserved as WIP parent `mlvzkprx`; generated reader locks excluded from commits, retained in working copy.
- Fresh crates.io inventory: every direct edge's locked, latest-compatible, and latest-stable versions agree.
- Coordinated host/guest set: Wasmtime 49.0.2, wit-bindgen 0.62.0; yanked yoke-derive 0.8.3 replaced by 0.8.4.
- Entropy migrated to getrandom 0.4.3; archunit 0.0.2 and Gungraun 0.20.0 verified through their consumers.
- Unjustified exact requirements removed for CBOR utilities, renamore, and portable-pty; ureq tilde and guest bindings exact requirement retain concrete reasons.
- Minimum compiler failures demonstrated missing serde_json macros/traits, crc32fast::hash, and WalkBuilder::require_git; engine resolution demonstrated shared serde/futures/JSON and nix/libc conflicts.
- Approved API/engine-backed minimums: serde 1.0.228, serde_json 1.0.120, futures 0.3.31, crc32fast 1.3.0, ignore 0.4.18, nix 0.31.3, fs2 0.4.3.
- Windows ARM64 minimum failed on fs2 0.4.0 → winapi 0.2 missing pointer types; fs2 0.4.1/0.4.2 retain that backend, approved 0.4.3 minimum passes.
- Locked, fresh-compatible, and direct-minimum checks pass for all eight runtime libraries; consumer checks leave checkout lockfile unchanged.
- CI-image checks: 496 tests, 40 binary E2E tests, documentation, architecture, and all 24 instruction budgets pass.
- Budget platform: Rust 1.99.0, glibc 2.41, Gungraun 0.20.0; independent rerun satisfies unchanged ±2 % band.
- Guest build regression failed under inherited native CPU flags, then passed with approved project-local Wasm target-family generic flags; two real host load/validation tests pass without a host configuration edit.
- All eight runtime libraries pass locked, fresh-compatible, and direct-minimum checks on Linux x86_64 and ARM64; ARM64 C compiler plus libc headers stayed inside disposable container.
- `smith-core` consumers pass all three checks on Windows/macOS x86_64 and ARM64; full graphs stop on missing Windows/macOS native C toolchains, not a verified dependency incompatibility.
- Explicit target handling covers either option order, invalid/missing target values, unchanged lockfile, and host default overriding ambient `CARGO_BUILD_TARGET`.
- Candidate probes and consumers declare their own workspace; enclosing-workspace regressions failed before this correction, then passed.
- Registry-identity/default-feature mutation scope: three mutants caught; current host-target scope catches both mutants.
- Broader mutation run is discarded: a workspace-context baseline failure produced false catches; corrected isolation has deterministic regressions, full nightly mutation evidence remains separate.
- Daily Luci jobs record gate exit statuses, retain failure artifacts, and publish only successful evidence; target matrix reflects proven scopes rather than implying full Windows/macOS verification.
- Nightly toolchain setup disables Rustup self-update because CI's custom Cargo home does not own Rustup.

## Remaining blockers

Hosted schedule/publication has no fresh run evidence; no push performed.
Windows/macOS full runtime-library graphs still lack native C toolchain verification; cross-target compilation does not prove foreign binary linking, runtime behavior, or frontend usability.
`cargo x release` remains undefined under Release Readiness; downstream checks are exposed and scheduled, not wired into a completed release gate.
Fresh audit has no advisory, yank, license, or source failure, but still emits three runtime duplicate-family warnings: getrandom, hashbrown, windows-sys.
Duplicate review found no released complete solution: ring retains getrandom 0.2 and Windows ARM64 windows-sys 0.52; Cranelift/Gimli and Kasuari retain hashbrown 0.16.
No warning suppression, portability reduction, host-system configuration edit, or unrelated issue closure applied.

Evidence commands and deterministic regressions remain in the implementation; local logs are under `/tmp/smith-dependency-exec-YD78WF/`, CI-image reports under `target/ci-image/report/`.
Plan remains incomplete until these evidence and integration gaps close.

## Exit

Latest-working dependency inventory is complete, automated update detection is observable, and all applicable gates pass.
Published findings distinguish verified compatibility from unresolved blockers.

## Stop conditions

- Required protected-file or temporary-workspace approval is missing.
- Upstream release cannot preserve a required Smith contract or supported target.
- Coordinated Wasm tooling lacks a verified compatible release set.
- Fresh or minimum resolution cannot be reproduced without changing the checkout graph.
- Required CI, registry, or pinned-platform evidence is unavailable.