fix(release): cascade exposed dependency breaks

[Kateřina Churanová (kate-shine)]

Summary

Release planning could ship a breaking API change inside a semver-compatible version.

cargo-semver-checks analyses each crate in isolation. But a crate's public API is not only what it declares — it is also every foreign type it re-exports. When bytesbuf breaks, bytesbuf_io breaks too, because bytesbuf_io's API is bytesbuf types:

// crates/bytesbuf_io/src/testing/fake_write.rs
pub fn contents(&self) -> &BytesBuf
pub fn reserve(&self, min_bytes: usize) -> BytesBuf

bytesbuf_io never changed, so semver-checks saw nothing, and the planner gave it the mechanical patch floor:

	before	after
bytesbuf	0.7.0 → 0.8.0	0.7.0 → 0.8.0
bytesbuf_io	0.7.0 → 0.7.1 ❌	0.7.0 → 0.8.0 ✅

That 0.7.1 is the bug: a patch release that breaks every downstream build, delivered automatically by cargo update.

This PR teaches the planner to combine semver-checks with the cargo_check_external_types allowlists each crate already declares, and to propagate incompatibility across public-API exposure edges to a fixpoint.

Work item: https://o365exchange.visualstudio.com/O365%20Core/_workitems/edit/7705926

---

What the cascade actually does

Running release-packages bytesbuf@breaking against today's workspace pulls in 9 crates, all breaking. Solid arrows are exposure edges; dashed arrows are dependencies that do not surface the type in their public API:

graph LR
    bytesbuf["bytesbuf 0.7.0 → 0.8.0"]
    bytesbuf_io["bytesbuf_io 0.7.0 → 0.8.0"]
    cachet["cachet 0.10.0 → 0.11.0"]
    multitude["multitude 0.7.1 → 0.8.0"]
    http_extensions["http_extensions 0.8.0 → 0.9.0"]
    seatbelt_http["seatbelt_http 0.6.0 → 0.7.0"]
    fetch["fetch 0.14.0 → 0.15.0"]
    fetch_hyper["fetch_hyper 0.5.0 → 0.6.0"]
    fetch_azure["fetch_azure 0.4.0 → 0.5.0"]

    bytesbuf --> bytesbuf_io
    bytesbuf --> cachet
    bytesbuf --> multitude
    bytesbuf --> http_extensions
    bytesbuf --> fetch
    bytesbuf -.-> fetch_hyper
    bytesbuf -.-> fetch_azure

    http_extensions --> seatbelt_http
    http_extensions --> fetch_hyper
    http_extensions --> fetch
    seatbelt_http --> fetch
    fetch_hyper -.-> fetch
    fetch --> fetch_azure

Loading

Why this needs a fixpoint, not a single pass

Look at fetch_hyper. It depends on bytesbuf but does not expose it — a single pass over bytesbuf's dependents would correctly leave it alone. It becomes breaking only on a later pass, through http_extensions:

graph LR
    A["bytesbuf — breaking"] -->|exposed| B["http_extensions — raised on pass 1"]
    B -->|exposed| C["fetch_hyper — raised on pass 2"]
    A -.->|"not exposed, no direct effect"| C

Loading

fetch_azure reaches breaking the same way, via fetch. So the cascade iterates until a pass strengthens nothing.

Each pass only ever raises, through a single choke point (Update-EntryForRequiredChangeType), which is what guarantees termination.

---

Planner flow

flowchart TD
    A["Parse tokens, e.g. bytesbuf@breaking"] --> B["requestedFolders"]
    B --> C["Self-floor: cargo-semver-checks per requested crate"]
    C --> D["BFS: every transitive published dependent joins at a patch floor"]
    D --> E{"Exposure fixpoint"}
    E --> F["Select entries whose planned version is an incompatible transition"]
    F --> G["Find selected published dependents: declared edges that may expose them, or reachable indirect crates that positively allowlist the defining crate"]
    G --> H["Raise to breaking, record cascade reason"]
    H -->|"something changed"| E
    E -->|"nothing changed"| I["Manual-review queue for proc-macro crates"]

Loading

---

Fail-closed policy

Exposure is decided from [package.metadata.cargo_check_external_types]. The guiding rule: an unknown must never permit a break to ship as compatible.

allowed_external_types	verdict	rationale
absent ($null)	exposed	no claim was made; CI validates merged code, the planner reads the working tree
[] (empty)	not exposed	a positive claim: "my API names nothing foreign"
root matches target	exposed	e.g. bytesbuf::* vs bytesbuf
root is an alias of target	exposed	package = "..." renames — see below
wildcard root (*, ?, [)	exposed	could match anything
malformed entry (non-string, blank)	exposed	carries no information
no matching root	not exposed

Note the asymmetry between absent and empty — that distinction is the one thing that makes the condition look inverted at a glance, so it is documented at the call site.

Two of these were fixed during review:

• Malformed entries (d42c6cb1) — -split coerces any operand to a string, so a non-string entry silently collapsed to '' and matched nothing. A typo'd allowlist therefore read as "not exposed".
• Renamed dependencies (7373a040) — a dependency declared package = "..." is nameable in Rust only under its alias, so its allowlist entry carries the alias while the planner compared against the real package name. The edge was detected, but the exposure test missed, and the break shipped tagged compatible. Get-WorkspacePackages now records a DepAliases map and the exposure test accepts either name.

---

-Force semantics

-Force writes the number you asked for and warns you. It does not assert that the incompatibility is absent, so it does not stop the cascade.

A pin honoured below a required breaking version writes a numerically compatible version over an API that is genuinely incompatible: b@1.1.0 is still compiled against a@2.0.0 and still exposes a::*, so its public API names different types than b@1.0.0 did — and a consumer of b = "1.0" upgrades into it silently under caret semantics. Keying the cascade off the planned version alone would stop it at exactly the crate whose break was suppressed:

graph LR
    a["a: 1.0.0 → 2.0.0, breaking"] -->|exposed| b["b: pinned 1.1.0 with --force, pin honoured, break suppressed not removed"]
    b -->|"cascade continues: the pin lowered the number, not the API"| c["c: raised to 2.0.0"]

Loading

The pin itself is still honoured verbatim — only the propagation decision changed.

Propagation is widened solely by PinHonoredAgainstCascade, and only when the suppressed requirement was itself breaking. That flag is set for any suppressed requirement, so a pin that merely undercuts an additive non-breaking requirement does not drag exposing dependents to a major release. Both branches route through the same Test-IsBreakingChange, which keeps 0.x semantics consistent between them.

---

Testing

497 Pester tests pass.

Regression coverage is deliberately split in two, because everything else in the suite builds synthetic package records and so only ever proves the planner correct about graphs the tests themselves invented:

• Unit — the exposure decision table above, including the negatives: trait-variant is a bytesbuf_io dependency that is deliberately not allowlisted and must stay unexposed, and bytesbuf being a strict prefix of bytesbuf_io must not cross-match either way.
• End-to-end (integration/ExposureCascade-RealWorkspace.Tests.ps1) — resolves a release set over the live workspace metadata and asserts the real bytesbuf → bytesbuf_io cascade, plus a negative control that bytesbuf@patch does not force a break.

The e2e test reads real manifests on purpose. Deleting bytesbuf::* from bytesbuf_io's allowlist is exactly how this fail-open would be reintroduced, and that must break the suite rather than pass against a stale snapshot.

Both regression layers were mutation-checked rather than assumed green:

mutation	result
Test-PackageExposesTarget reverted to the original fail-open	4 of 9 e2e assertions fail
Test-EntryPlansBreakingRelease keyed off the change-type tag instead of the planned version	1 test fails — and it is the new one; nothing else in 454 noticed

---

Commits

40b112bc	cascade exposed dependency breaks
d42c6cb1	fail closed on malformed allowed_external_types entries
0a9ec0c5	document why an absent allowlist still counts as exposure
895ed215	split the exposure fixpoint into named helpers
7373a040	match exposure allowlists against renamed dependency aliases
58ab2412	pin the bytesbuf/bytesbuf_io cascade against real manifests

Known gap (not in scope)

Deps retains both normal and build dependency kinds, so a build-only edge could over-cascade. It is unreachable today — all four workspace build edges originate from publish = false crates, which the Published filter already excludes — and it fails in the safe direction (an unnecessary bump, never a silent break). The fix needs per-edge kind metadata, tracked in AB#7729476.

[Copilot]

Pull request overview

This PR hardens the release planner’s cascade logic by combining cargo-semver-checks results with exposed external-type metadata so that breaking dependency bumps propagate to dependents whose public APIs expose those dependency types (including through chains) and missing/wildcard metadata is handled conservatively.

Changes:

• Extend workspace package metadata to include allowed_external_types and add a conservative exposure check helper.
• Add a fixpoint-based “exposed dependency” cascade pass to strengthen dependents to breaking when they expose an incompatibly bumped dependency.
• Add unit + scenario regression coverage for the bytesbuf → bytesbuf_io failure mode and related edge cases.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
scripts/tests/Pester/unit/release-packages/ResolveReleaseSet.Tests.ps1	Updates baseline stubs to carry external-type metadata and adds focused unit tests for the new exposure-driven cascade behavior.
scripts/tests/Pester/scenarios/S27-proc-macro-recursive-review.scenario.psd1	Adds AllowedExternalTypes to keep scenario expectations stable under the new conservative exposure rules.
scripts/tests/Pester/scenarios/S15-auto-upgrade-of-user-source.scenario.psd1	Shifts the scenario to rely on exposure metadata rather than an explicit semver verdict override.
scripts/release-packages.ps1	Updates release-planner documentation to describe the new exposed-dependency cascade behavior and conservative handling.
scripts/lib/releasing.ps1	Plumbs AllowedExternalTypes from cargo metadata and introduces Test-PackageExposesTarget for exposure checks.
scripts/lib/release-flow.ps1	Implements the fixpoint cascade pass that upgrades dependents to breaking when they expose breaking dependency version transitions.
docs/releasing.md	Updates the release documentation to explain why exposed dependency version transitions require an additional cascade beyond rustdoc comparison.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.0%. Comparing base (a650c15) to head (f7e228d).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #646   +/-   ##
=======================================
  Coverage   100.0%   100.0%           
=======================================
  Files         503      503           
  Lines       57407    57407           
=======================================
  Hits        57407    57407           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Kateřina Churanová (kate-shine)]

GHCP: Fixed in d42c6cb, though the diagnosis needed correcting — the conclusion was right for the wrong reason.

The comment predicts $root becomes $null and .Contains(...) throws. It doesn't. PowerShell's -split coerces any operand to a string, so there is no crash to guard against:

$null      -> ''                             (String)
42         -> '42'                            (String)
@{a=1}     -> 'System.Collections.Hashtable'  (String)

The actual defect is quieter and worse. A malformed entry collapses to '', matches neither the wildcard test nor the target name, and the loop falls through to return $false — no exposure. For a function whose documented contract is "an unknown exposure must not permit a breaking dependency bump to ship as a compatible release", that is precisely inverted: instead of aborting release planning loudly, it fails open and ships the break. A crash would have been the safer failure mode.

So the recommended behaviour ("treat malformed entries as possible exposure") is exactly right and is what landed: any entry that is not a usable non-empty string now returns $true.

Added 8 unit tests for Test-PackageExposesTarget, which had no direct coverage. I verified they are genuine regression tests by stashing the fix and re-running — the two malformed-entry cases fail against the old code with Expected $true ... but got $false, confirming fail-open rather than a throw. Also extended the doc comment, which only mentioned missing metadata.

Full suite: 431 passed, 0 failed.

Separately, on the red checks: all six are GitHub Actions infrastructure, not this change. Five (extended-analysis ×3, model-checking, anvil-pr / pr-test (windows)) died with Service Unavailable — Failed to resolve action download info before executing a step, one was cancelled, and required-checks is a 4-second rollup of those. Every substantive job passed, including both script-tests legs, semver, external-type-exposure, testing and static-analysis across all four platforms.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Suppressed comments (2)

scripts/lib/release-flow.ps1:374

• Deps contains both normal and build dependencies (scripts/lib/releasing.ps1:591-595), so this predicate treats a build-only edge as a possible public-API exposure. With missing or wildcard metadata, a breaking build-dependency bump therefore forces the dependent to breaking, even though build-dependency types cannot appear in that crate's Rust API. Preserve dependency kind in the workspace model and apply this exposure cascade only to normal dependency edges.

    return @($WorkspaceBaseline | Where-Object {
            $_.Published -and
            -not $_.IsProcMacroOnly -and
            $_.Deps -contains $targetCargoName -and
            $Resolved.Contains($_.Folder) -and
            (Test-PackageExposesTarget -Dependent $_ -TargetPackageName $TargetPackage.Name)

scripts/lib/release-flow.ps1:646

• The new -Force behavior that bases propagation on the pinned version rather than the upgraded severity tag is not covered by the added tests. Add an exposed A → B → C chain where B is explicitly pinned to a non-breaking version with -Force; assert B retains the pin and breaking tag while C remains at its mechanical patch floor. This protects the control path described here from accidentally reverting to tag-based propagation.

    # cargo-semver-checks compares one crate's rustdoc API and cannot identify
    # that an unchanged signature now names a type from an incompatible version
    # of an external crate. Propagate that condition over direct dependency edges
    # until no dependent is strengthened. Use the version that will actually be
    # written, not EffectiveChangeType, so -Force pins do not create a fictitious
    # breaking transition farther up the graph.

[Kateřina Churanová (kate-shine)]

GHCP: Responses to the two suppressed comments on this review.

release-flow.ps1:646 — missing -Force propagation coverage. Agreed, genuine gap. Added two tests in ResolveReleaseSet.Tests.ps1 (7373a04) over an exposed a -> b -> c chain:

• b pinned to 1.1.0 under -Force: b keeps the pin and the breaking tag, and c stays at its BFS patch floor 1.0.1.
• b pinned to 2.0.0: the cascade resumes and c inherits the break.

This pins Test-EntryPlansBreakingRelease's deliberate use of EffectiveTargetVersion over EffectiveChangeType. I mutation-checked it — swapping the function back to the tag makes the first test fail and nothing else in the suite notices, so the coverage gap was real.

release-flow.ps1:374 — build-dependency edges. Mechanism confirmed: Get-WorkspacePackages filters only kind dev, so Deps carries normal and build. Not fixing in this PR, for two reasons:

1. Unreachable today. There are 4 workspace build edges (rest_over_grpc_examples -> rest_over_grpc, and rest_over_grpc_tests -> {http_path_template, rest_over_grpc, routerama}) and every source is publish = false, so the $_.Published filter already excludes them.
2. It fails in the safe direction — an unnecessary bump, not a silent break — unlike the rename issue above.

The real fix is per-edge kind metadata, which is the same model change as DepAliases and better done deliberately than folded into this PR. Filing a follow-up work item.

Full suite: 441/441.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

scripts/lib/releasing.ps1:614

• The critical rename path is not exercised from Cargo metadata: the unit tests construct DepAliases directly (already normalized), and the live-workspace test only covers an unrenamed edge. A regression in reading dependency.rename or converting bytes-buf to bytes_buf would therefore restore the fail-open behavior while all added tests still pass. Add a synthetic workspace with alias = { package = "dependency", ... }, load it through Get-WorkspacePackages, and assert that the alias-rooted allowlist drives the cascade.

            $renameProp = $dep.PSObject.Properties['rename']
            if ($renameProp -and -not [string]::IsNullOrWhiteSpace($renameProp.Value)) {
                $alias = ([string]$renameProp.Value).Replace('-', '_')
                # A package may be depended on more than once under different
                # aliases (per-target or per-feature), so collect them all.
                $depAliases[$depCargoName] = @(@($depAliases[$depCargoName]) + $alias |
                        Where-Object { $_ } | Sort-Object -Unique)

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

Suppressed comments (3)

scripts/lib/release-flow.ps1:500

• The planner pass is no longer direct-edge-only: lines 681-685 and Get-PublishedDependentsExposingTarget explicitly include indirect defining-crate edges. Keeping the function contract phrased this way makes future maintenance likely to drop the indirect behavior that the new regression tests protect.

#      floored at patch. A second direct-edge pass raises a dependent to breaking
#      when it exposes a dependency whose planned version transition is
#      incompatible. The pass repeats to a fixpoint so exposure chains cascade.

scripts/release-packages.ps1:68

• This help text now understates the implemented cascade: Get-PublishedDependentsExposingTarget also handles reachable indirect dependents whose allowlist names the type's defining crate. Describing only direct edges leaves users unaware of releases such as typespec_client_core -> ... -> fetch_azure; document both direct fail-closed edges and positively evidenced indirect edges.

    Exposing a dependency whose planned version transition is breaking floors
    the dependent at `breaking`, recursively through direct dependency edges.

docs/releasing.md:238

• This description is stale after adding defining-crate exposure edges: the implementation does not consult only direct edges. It also selects reachable indirect dependents when their allowlist explicitly names the defining crate, with different missing/malformed-metadata semantics. Please document that distinction so the release policy matches the planner.

each direct dependency edge, the planner therefore also consults
`[package.metadata.cargo_check_external_types].allowed_external_types`.
If the dependency's planned version transition is breaking and the
dependent allows that dependency's types in its public API, the dependent
is floored at `breaking`. The planner repeats this check to a fixpoint so
the result propagates through chains such as `bytesbuf` → `bytesbuf_io` →
another facade.

[Kateřina Churanová (kate-shine)]

GHCP: All three fixed in 7cc3fc0 — correct on every count. 7865720 changed the behaviour and left three descriptions behind, which is the same mistake wukchung caught earlier in this PR, so this time I swept the rest of the scripts and docs rather than only fixing what was reported. The remaining "direct dependency/dependent" references cover the manual review chain and changelog reason attribution, which genuinely are direct-only and are unaffected.

Taking the docs/releasing.md point in particular: the differing missing-metadata semantics are now documented explicitly, since a future reader could easily mistake them for an inconsistency rather than a deliberate asymmetry:

• Direct dependency edges fail closed — absent, malformed or wildcard metadata all count as possible exposure, because an unknown must not ship a break as compatible.
• Indirect edges require an explicit allowlist entry naming the transitive dependency (or a rename alias). Failing closed here would match every transitive dependency of every crate that declares no allowlist and force unrelated crates breaking. Nothing is missed: a crate with no allowlist that really does expose the type still fails closed on its direct edge to whichever intermediate carries it, and the fixpoint propagates that upward.

fetch_azure is used as the worked example in both the docs and the help text, since it documents the mechanism in its own manifest — it allowlists typespec_client_core::* for a trait azure_core re-exports, while depending only on azure_core. I checked that against the manifest rather than quoting it from memory.

Comments and docs only, no behaviour change; unit suite 380/380.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.