Diagnostics output-quality follow-ups: multi-hop holdback stories

[StefanKarpinski]

Rewritten 2026-09-12. Item 1 (bound direction) moved to #118, which was closed on 2026-09-15: its premise did not hold. Item 3 is done. What is left is one item, and it is blocked.

Quality ceilings in the diagnosis reports, none blocking, each with an understood path.

Open

Holdback stories would be one hop. A holdback chain would name the responsible user constraints plus the direct incompatibility; one caused by a chain of third-party bounds — "julia held back because A needs B needs old-C" — would need the conflict-story machinery pointed at a holdback rather than a cluster.

Unreachable until holdbacks exist at all (#52), so "one hop" is a ceiling on something unbuilt. File a case under it when one turns up.

Also recorded here

Two limitations of the dependency chains, disclosed during #86 and kept here because #85 is closed. Both are cases where a real report reading badly is the signal to act, which is what this issue is for.

• Some conflicts get no story at all. The chain follows a forced descent and stops at the first pass that starves something, so a conflict whose explanation needs joint reasoning past that point gets only its requirement and availability lines. Measured at 3 of 99 conflicts across two sweeps. A direct-edge-only rule would have been far worse (36% with nothing to say), so this is the tail of a good heuristic rather than a broken one.
• Where several packages starve at once, which one is named is a preference. Bounds are symmetric, so simultaneous starvation is the usual case. The order is: not a requirement, then touches a package the query emptied, then shortest, then by name. Deterministic and reasonable, but a different choice would give a different, equally true story.

Closed out

• Bound direction → Carry bound direction in PkgInfo, to extend upstream fixes past the user's own constraints #118, now closed. PkgInfo still records compatibility symmetrically, and that turns out not to cost the page anything. A conflict line states an implication, not authorship: A 1.0 constrains C to 1–2 is true whichever side's Compat.toml declared the bound, because the other reading is the contrapositive and so the same clause — checked by entails, not merely asserted. And the one place authorship matters, the addressee of an upstream fix, already has direction: it reads PkgData.compat from the provider rather than the symmetric matrix. What Carry bound direction in PkgInfo, to extend upstream fixes past the user's own constraints #118 would have bought is naming which side declared a bound, where the high-order bit — these versions cannot coexist — is symmetric and already stated truthfully.
• Per-source fix granularity — done, by One map, one constraint type #79 and Diagnose an unsatisfiable resolve #73 rather than by the mark_necessary! column split this issue proposed. Constraints are one map keyed by kind, and the diagnosis emits one Action{P}(kind, pkg) per excluding kind, so a fix names the specific constraint. Cover the cheapest fixes by exact products, one conflict per leading menu #107 went further: the cheapest repairs are decomposed into independent blocks and covered by exact products, with completeness asserted per report.

One framing note carried forward: this issue was written against #57's reports, and #57 was superseded rather than merged. The shipped reports are #105/#107's — which changes nothing about the item above, a property of holdbacks rather than of the report architecture.

---

🤖 Maintained with Claude Code.

[StefanKarpinski]

Two of the three items here have moved since class space landed (#71).

Per-source fix granularity may be free now. This was filed when relaxations were licensed at whole-package granularity, so a fix had to name every source constraining a package rather than the minimal subset. In class space a user constraint acts by emptying a class, and which sources emptied it is answered per member by class_exclusions with no solver involved — so the information the finer granularity needs is already computed. What remains is whether fix enumeration should relax one source at a time (finer menu, more correction sets to enumerate) or keep grouping them. Worth revisiting when a real report reads badly, not before.

The bound-direction bit is still wanted, and is now cheaper to add. PkgInfo records compatibility symmetrically, so a report says "A works with C only at 1–2" and an upstream suggestion has to name both sides. Carrying the declaring side would let it name the package whose Project.toml actually holds the line. It was cut from #71 deliberately to keep that change to one thing; adding it now is a matrix-format change of its own.

Multi-hop holdback stories are unchanged: the chain names the responsible user constraints plus the direct incompatibility, and a holdback caused by a chain of third-party bounds would need the conflict-story machinery pointed at a holdback rather than a cluster. Still waiting for a real case to demand it.

[StefanKarpinski]

Status against current main (2480f3f), after #73 and #79 merged.

Item 3 (per-source fix granularity) is done. #79 made a problem's constraints a single map keyed by kind, and #73's diagnosis emits one Action{P}(kind, pkg) per excluding kind (src/Diagnostics.jl, correction_actions), so fixes already name the specific constraint rather than relaxing a package's constraints as a unit. Reports read "relax your compat on PrettyTables", and a pin would be named as a pin. The mark_necessary! column-splitting sketch in this item is no longer needed — class space got there by a different route.

Items 1 and 2 are unchanged and still accurate.

1. Bound facts are still undirected: PkgInfo records compatibility symmetrically, so a report cannot name which side's Project.toml carries the line. Still needs a PkgInfo change to carry direction.
2. Holdback stories don't exist yet at all — Diagnostics should explain steering surprises: why a resolve was held back to an older julia (or package) version #52 is unstarted — so "one hop" is still the ceiling whenever they do.

One correction to this issue's framing: it describes these as ceilings in "#57's reports", and #57 was superseded rather than merged. The shipped reports are #73's. That does not change items 1 or 2, which are properties of PkgInfo and of holdbacks, not of the diagnosis architecture.

[StefanKarpinski]

Two limitations of the dependency chains added in #86, disclosed during that work and worth recording here since #85 is closed.

Some conflicts get no story at all. The chain follows a forced descent — from the requirements, along dependencies every live version has, narrowing each package by what the packages already reached admit. It stops at the first pass that starves something, so a conflict whose explanation needs joint reasoning past that point gets no relation facts, only the requirement and availability lines. Measured at 3 of 99 conflicts across two sweeps. A direct-edge-only rule would have been far worse (36% with nothing to say), so this is the tail of a good heuristic rather than a broken one.

Where several packages starve at once, which one gets named is a preference, not a consequence. Bounds are symmetric, so simultaneous starvation is the usual case rather than the exception. The current order is: not a requirement, then touches a package the query emptied, then shortest, then by name. Reasonable, and deterministic, but nothing makes it the right one — a different choice would produce a different, equally true story.

Both are cases where a real report reading badly is the signal to act, which is what this issue is for.

[StefanKarpinski]

Status against main (d59bcd2), after the diagnosis rebuild in #104/#105/#107.

Item 3 (per-source fix granularity) stays done, as recorded in the 2026-08-17 update, and #107 went further than "one action per excluding kind": the cheapest repairs are now decomposed into independent blocks and covered by exact products, with completeness asserted per report (covers_family). Fix granularity is no longer a quality ceiling in any form this issue anticipated.

Item 1 (bound facts are undirected) is unchanged and is now the last of the three. PkgInfo still records compatibility symmetrically — there is no direction bit and no parallel table — so a report still cannot name which side's Project.toml carries the line, and an upstream suggestion still has to name both. The rebuild did not touch this: it changed how facts are selected, verified and printed, not what the matrix records. Still a PkgInfo format change, now on a v4 file format that has absorbed two such changes already.

Item 2 (holdback stories are one hop) is unchanged and still unreachable, because holdbacks still do not exist (#52).

The two #86 limitations recorded above are also unchanged: some conflicts get no relation facts at all (3 of 99 measured), and where several packages starve at once, which one is named is a deterministic preference rather than a consequence. Both are still "a real report reading badly is the signal", which is what this issue is for.

One framing note carried forward: this issue describes these as ceilings in #57's reports, and #57 was superseded. They are now ceilings in #105/#107's reports — which does not change items 1 or 2, since both are properties of PkgInfo and of holdbacks rather than of the report architecture.

---

🤖 Triaged with Claude Code.

[StefanKarpinski]

Correction to my status note above, found while capturing the archived prototypes as #112 and #113.

I wrote that item 1 "is unchanged and is now the last of the three". The limitation is unchanged — PkgInfo records compatibility symmetrically, there is no direction bit, and a report cannot name which side's Project.toml carries the line. That part stands.

But item 1's stated payoff refers to a feature that does not exist. This issue justifies carrying direction by "upstream suggestions name the package whose Project.toml actually contains the line", and upstream suggestions — "a release of A or C relaxing their compat on each other would fix this" — are nowhere in main. No upstream in src/, and none in the history: rank_upstream! and superseded live only on archive/holdbacks-prototype (3993297), which was never merged.

So the ordering is the other way round from what this issue assumes. Bound direction is not a prerequisite for upstream suggestions that already ship; both are unbuilt, and direction only pays off if the suggestions come back. That is now tracked as decision 3 on #113.

Item 1 therefore needs either a different justification or an explicit dependency on #113. Nothing about the underlying PkgInfo gap has changed.

---

🤖 Triaged with Claude Code.

[StefanKarpinski]

Supersedes my correction above. Upstream fixes shipped in #114 (2f6cd27), so the payoff item 1 names does exist now. But the payoff has moved, and the new version is sharper than either the original or my correction.

#114 does not resolve bound direction. It sidesteps it, by declining the cases that need it. From the qualification rules:

A bound contradicted only by another registry package's bound is not offered: a sentence that blamed two maintainers would judge which is at fault, and the page judges nothing. One release, one bound, one addressee.

So the page offers an upstream fix only where a registry bound meets the user's own constraint — where there is exactly one maintainer to name, and naming them requires no knowledge of who declared what. Registry-versus-registry conflicts are explained and left there.

That is precisely the gap direction would close. With a direction bit, the page could name one addressee in the registry-versus-registry case without judging anything: the bound is in somebody's Project.toml, and direction says whose. The scope restriction in condition 1 exists because that fact is unrecoverable, not because the case is uninteresting.

So item 1 restates as:

PkgInfo records compatibility symmetrically, so an upstream fix can only be offered where a bound meets the user's own constraint. Carrying the declaring side would extend upstream fixes to conflicts between two registry packages — currently the largest class the feature declines by design.

That is a much better justification than the original "name the package whose Project.toml actually contains the line", because it names a user-visible capability rather than a wording improvement, and it comes with a measurement worth taking first: how many conflicts are declined by condition 1? If registry-versus-registry conflicts are rare in practice, the PkgInfo format change is not worth it. If they are common, this is the biggest remaining diagnostics gap.

That measurement is the work item, on the principle #64 now records for #60 and #91.

---

🤖 Triaged with Claude Code.