nordisk/nornir

Faithful dry-run — making release doctor a complete rehearsal of cargo publish

The release doctor's DRY-RUN must be a FAITHFUL, COMPLETE rehearsal of a real cargo publish: a green dry-run has to guarantee a green real publish. It recently did not. The doctor's --publish-dry-run printed an "all clear" for nornir 0.5.3, but the real publish fail-stopped on a correctness blocker — a dependency (draupnir) carried new API that was not yet published to crates.io, so nornir's verify build compiled against local source the registry copy did not have. A dry-run that misses what the real run hits is worse than no dry-run: it manufactures false confidence before an irreversible cascade.

This is the authoritative spec. It (1) enumerates every step a real cargo publish performs and every way it can fail, with cargo source citations; (2) maps each to a gap table — does cargo publish --dry-run cover it, and if not exactly what the doctor must simulate itself, cross-referenced to what the doctor already has (preflight.rs, registry.rs, source_drift.rs) vs what is missing; and (3) gives the implement agent an executable plan for a FAT-client up-front rehearsal that early-fails before any mutation.

Companions: release-doctor-design.md (the four-stage model), release-doctor-rejection-coverage.md (the live rejection matrix), release-publish-traps.md (field-caught traps). Engine: dwarves::release_doctor::preflight, dwarves::release_doctor::registry, dwarves::release_doctor::source_drift; CLI wiring src/bin/nornir.rs (ReleaseOp::Doctor --publish).

⚠ MOVED (doctrine L5a — release is a build op). The release-doctor ENGINE this spec covers moved from nornir/src/release/ to dwarves::release_doctor (dwarves/crates/dwarves/src/release_doctor/). Every bare preflight.rs, registry.rs, source_drift.rs, publish.rs, doctor.rs filename + line citation below now resolves under that dwarves path (dwarves/crates/dwarves/src/ release_doctor/<file>), not nornir/src/release/. Line numbers are historical and may have drifted since the move; treat them as landmarks, not exact offsets. The nornir release doctor verbs are now still-working shims over dwarves release.

The core insight

cargo publish --dry-run is a LOCAL validator, not a registry rehearsal. It runs everything cargo can decide from the working tree — packaging, manifest normalization, the verify build — but it provably skips every check that lives on the registry: the actual upload, token/credential acquisition, the authoritative version-already-exists check, crate-name ownership, rate limits, the tarball size cap, the wildcard-dependency ban, and — the one that bit us — it never confirms that each dependency's required version is actually live on the registry. It resolves the dependency graph against the LOCAL Cargo.lock and a workspace where path-deps mask their registry twins, so an un-published upstream version is invisible.

The doctor's job is therefore not to re-run cargo publish --dry-run and trust it. It is to run the dry-run plus a battery of registry-side simulations that reproduce, up front and offline-of-mutation, exactly the checks cargo defers to the server — and to early-fail before the first bump commit if any would fail.

Part 1 — the full ordered checklist of a real cargo publish

Line numbers are rust-lang/cargo master. Files: src/cargo/ops/registry/publish.rs (driver), src/cargo/ops/cargo_package/{mod,vcs,verify}.rs (packaging), src/cargo/util/toml/mod.rs (manifest normalization), src/cargo/ops/mod.rs (check_dep_has_version). Entry point: publish() at publish.rs:72.

Failure modes that live ONLY on the crates.io server

The cargo CLIENT does not enforce these; they are returned by registry.publish() at publish.rs:667 and thus surface only at real upload time:

• Tarball size cap (10 MiB default). No client threshold exists — grep of publish.rs, cargo_package/mod.rs, registry/mod.rs finds only uncompressed_size bookkeeping (mod.rs:888-942). Server: "max upload size is: N".
• Wildcard (*) dependency ban. Enforced server-side ("wildcard (*) dependency constraints are not allowed on crates.io"). The only wildcard checks in toml/mod.rs:2110/2130 are for [replace], unrelated.
• Crate-name ownership / squat — "this crate exists but you don't seem to be an owner" (403).
• Rate limits — new versions per 24h, new crates per week (429).
• Verified-email / token validity — 403 without a verified email or valid token.
• Field length / count caps, category-slug validity, too-similar-name, reserved names — validated in crates.io src/controllers/krate/publish.rs.

Part 2 — gap table: cargo publish --dry-run coverage, and what the doctor must fill

Legend for "dry-run": ✅ performed identically to a real run · ⚠ performed but DOWNGRADED (warning, not error) · ❌ SKIPPED entirely. "Doctor today" cites the existing check; MISSING flags a real gap the implement agent must close.

The one gap that caused the incident, stated precisely

The draupnir failure is row S6′. Two mechanisms let an un-published dependency version pass the dry-run:

1. Path-dep masking. In the constellation, a consumer declares a member dep as dep = { version = "X", path = "../dep" }. cargo publish strips the path (S7f, toml/mod.rs:3254-3260) so the PUBLISHED manifest needs X live on crates.io — but the LOCAL verify build and lockfile resolution use the path, so they never touch the registry. If X was bumped locally but not yet published, the local build is green and the real publish's consumers break.
2. AlreadyPublished-but-edited upstream. The dep's version is unchanged and IS on crates.io, but its local source added new API a to-publish consumer uses. The verify build compiles against local source (path-masked) and passes; the published consumer resolves the older registry bytes and fails.

cargo publish --dry-run catches (2) ONLY when it happens to be built without the path (rare) and never reliably catches (1). The doctor must therefore assert, independently of any compile, that every dependency requirement is satisfied by a live non-yanked registry version — or, if the dep is a constellation member the cascade will publish forward, that the cascade publishes it first.

Part 3 — implementation plan for the FAT-client faithful dry-run

Goal: nornir release doctor --publish --publish-dry-run (and the real --publish) run the FULL registry-side rehearsal up front and early-fail before any mutation — no bump, no bump-commit, no release/staging branch, no cargo package, no cargo publish, no push has run when a blocker is reported. The dry-run and the real run share ONE code path and produce the SAME verdict; the only difference is the dry-run stops at the gate.

The architecture already exists and is mostly wired at nornir.rs:11553-11717. The remaining work is closing S6′ and hardening parity. Do NOT edit doctor.rs for the checks — they belong in preflight.rs / registry.rs (pure + unit-tested); doctor.rs only orchestrates.

3.1 Parity invariant (already landed — guard it)

preflight_verify_mode(_publish_dry_run) -> VerifyMode::On (preflight.rs:307) is the fix that closed the original false-clear: the verify build and source-drift pass run in BOTH modes. Keep the parameter ignored; the unit test that pins this must stay. gate_verdict (preflight.rs:336) is pure over the report and used identically by both modes — correctness blockers (is_correctness_blocker: VerifyFailed | StaleSourceDrift) are NEVER forceable; soft blockers abort unless --force.

3.2 Close S6′ — the missing per-dependency published-req check

Add a pure function in preflight.rs, e.g.:

pub fn unpublished_dep_reqs(
    plans: &[RepoPlan],
    probe: &dyn RegistryProbe,               // req_satisfied already exists
    cascade_publishes: &BTreeMap<String,String>,
) -> Vec<Issue>

For every planned crate, walk its NORMAL + BUILD dependencies (reuse for_each_published_dep / manifest_all_dep_names, and read the version req via dep_version_req). For each dep with a version requirement:

1. If the dep is a member the cascade will publish forward at a version satisfying the req (cascade_publishes, hyphen/underscore-canonicalized like skew_is_cascade_resolvable) → OK (order covers it) → NOTE.

2. Else call probe.req_satisfied(dep, req):

   • Some(true) → OK.
   • Some(false) → blocker IssueKind::UnpublishableDep (or a new UnpublishedDepVersion): "dep {d} requires {req} but crates.io serves no non-yanked version satisfying it — publish {d} first". This is the draupnir catch, compile-independent. Classify it as a correctness blocker (un-forceable) since forcing ships a crate that cannot resolve.
   • None (network/unparsable) → NOTE (degrade-safe, never a false block).

This makes the doctor prove S6′ directly instead of hoping the verify build's compiler stumbles on it. It also fires for path-masked deps because it reads the declared version req, not the resolved path. Unit-test with an injected probe (no network), mirroring registry.rs's test style.

3.3 Up-front rehearsal ordering (the early-fail battery)

Run in this order inside the --publish handler's preflight block, BEFORE the cascade loop (this is the existing structure at nornir.rs:11553+; slot 3.2 in):

1. Selection — compute plans (per-repo publish_set, honoring --only/--exclude/--publish-from, private-repo skip, drift-skip).
2. Ownership (S10) — registry::ownership_blocks over all names; bail on any foreign-owned name. Warn (don't bail) when no token/login.
3. Token presence (S4) — if real publish (not dry-run) and no token → bail early with the "create a token / cargo login" guidance (lane ③).
4. preflight::run (S1–S7, S8, S9-adjacent) with VerifyMode::On, CratesIoProbe, the registry backend, and the bump-aware cascade_publishes map — produces metadata, name, manifest, path-dep, registry-skew, registry-desync, versioned-path-dev-dep, oversized-tarball, and verify-build (dep-API-skew) issues.
5. unpublished_dep_reqs (S6′, NEW) — append its issues/notes.
6. source_drift_issues (S8′) — append (verify-On only).
7. Topological root-cause — root_cause::analyze over the flat issue list so the operator sees the ONE root, not N downstream symptoms.
8. gate_verdict — Proceed (dry-run stops here and reports "would publish"; real run continues) / BlockCorrectness (never forceable) / BlockSoft (forceable). The dry-run and real run print the SAME verdict.

Every network probe is best-effort: an unreachable registry degrades a check to a NOTE, never a false block (the established doctrine in registry.rs).

3.4 What "faithful" now means, testably

A green dry-run guarantees a green real publish iff, for the planned set, all of: version-not-already-live (S5) · required metadata (S7b) · valid name/semver/SPDX/ manifest (S7f) · every dep has a version req and none cross-registry (S6) · every dep req is satisfied by a live registry version or published forward by the cascade (S6′) · no dep-API skew in the verify build (S8) · no same-version source drift (S8′) · name owned by us or free (S10) · tarball ≤ 10 MiB (S10) · no wildcard dep (S10) · no cycle (S9) · token present (S4). The only real-publish outcomes a green dry-run cannot prove are rate-limit (S10, retry-handled) and index-propagation timing (S11, wait_for_index-handled) — both transient, not correctness, and both handled in the cascade itself.

Add a parity regression test: a fixture where a consumer path-masks an un-published member version must produce IDENTICAL blocking verdicts under --publish-dry-run and --publish (both BlockCorrectness). That fixture is the draupnir incident, frozen.

Summary of the gaps cargo publish --dry-run leaves (and their owner)

1. Dependency published-ness (S6′) — the draupnir gap. Dry-run never confirms each dep req resolves to a LIVE registry version; path-deps mask it. → NEW unpublished_dep_reqs per-edge check (3.2), correctness-class.
2. Version already live (S5) — downgraded to a warning. → RegistrySkew (have).
3. Local behind registry / desync — not a cargo concept at all. → RegistryDesync (have).
4. Crate-name ownership (S10) — server-only. → ownership_blocks (have).
5. Token/credential validity (S4) — skipped in dry-run. → token+login probe (have; ensure it BAILS on real publish with no token).
6. Tarball >10 MiB (S10) — no client check. → OversizedTarball (have).
7. Wildcard * dep (S10) — server-only. → manifest scan (have).
8. Same-version source drift (S8′) — verify never diffs bytes. → StaleSourceDrift (have).
9. Rate limit (S10) / index propagation (S11) — transient, runtime-only; retry + wait_for_index in the cascade.

Nine deferred registry checks; the doctor already covers eight. Closing #1 (S6′) with a direct per-dependency published-req assertion is the single remaining change that makes a green dry-run a real guarantee.