Say "Stuck" and "Expected", and name the faulty reference

No word built on "leak" belongs on an object. A leak is one faulty
reference that should have been cleared, and everything under it is
retained by that single mistake — so "Leaked" on twenty objects points a
reader at the twenty rather than at the one thing to fix. "Stuck" says
the object's situation without accusing it, and it is the only candidate
that asks a question instead of closing one: something is holding this,
what? "Expected" says its presence in memory is legitimate at this point
in the app's life.

No other analyser has a verdict like this to borrow words from, checked
before choosing: JProfiler classifies objects by reference type and by
age, YourKit by reachability scope, MAT and dotMemory name places rather
than objects. What they share is the frame — JProfiler asks whether
objects "are still legitimately on the heap or if a faulty reference
keeps them alive" — which is where the name for the culprit edge comes
from, and it is now what the leaks screen and the KDoc call it.

An object nothing reaches any more stays Stuck like any other: it was
expected to be gone, and only the collector not having run keeps it
here. A fourth value would have made the verdict mean something
different in one corner of the window.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: pyricau

docs/shark-explorer-changelog.md

@@ -30,11 +30,11 @@ uses, without the one for a newly recognized library leak:
   See [Take notes](shark-explorer.md#take-notes).
 * ✨ Right click ← or → for the list of everywhere that arrow leads, so going back four moves is one
   click rather than four.
-* ✨ **Verdict**: whether the object a tab is on leaked — `✗ Leaked`, `✓ Needed` or `? Unknown` — is the first
-  thing the **What it is** panel says, in the same colours a chain uses, and the pencil beside it overrules
-  the verdict: a reason is required, kept with it, and what you overruled is recorded beside it. Where a
-  verdict you set contradicts another one, every verdict it disagrees with is listed with the reason it was
-  given, and keeping yours flips them. The **Leaks** screen follows what you set, since marking an object as
-  leaked makes it a leak and takes whatever it holds off the list. Kept between runs in
+* ✨ **Verdict**: whether the object a tab is on is stuck in memory — `✗ Stuck`, `✓ Expected` or `? Unknown`
+  — is the first thing the **What it is** panel says, in the same colours a chain uses, and the pencil beside
+  it overrules the verdict: a reason is required, kept with it, and what you overruled is recorded beside it.
+  Where a verdict you set contradicts another one, every verdict it disagrees with is listed with the reason
+  it was given, and keeping yours flips them. The **Leaks** screen follows what you set, since marking an
+  object as stuck makes it a leak and takes whatever it holds off the list. Kept between runs in
   `~/.shark-explorer/leak-statuses`, one file per heap dump.
-  See [Say what leaked](shark-explorer.md#say-what-leaked).
+  See [The verdict](shark-explorer.md#the-verdict).

docs/shark-explorer.md

@@ -70,8 +70,8 @@ a few seconds.
   Java heap from API 26 to 34, and for those the app offers to fetch them off the device the dump came from.
 * **Object list** is the whole dump as a searchable list, and **Starred** keeps the objects you want to
   come back to.
-* **Whether the object a tab is on leaked is the first thing "What it is" says**, and you can overrule it —
-  see [Say what leaked](#say-what-leaked).
+* **The verdict on the object a tab is on is the first thing "What it is" says** — `Stuck`, `Expected` or
+  `Unknown` — and you can overrule it, see [The verdict](#the-verdict).
 * Every location takes a **note**, in markdown, kept between runs — see [Take notes](#take-notes).
 
 ## Link to a tab
@@ -149,51 +149,57 @@ Since a `shark://` link names a window, a link written into a note stops working
 — see above. Copy one for the tab you want to come back to *while you are writing about it*, and it will
 take you there for as long as that window is open.
 
-## Say what leaked
+## The verdict
 
-At the top of **What it is**, under the object's name, is the **Verdict** on it — `✗ Leaked`, `✓ Needed`, or
+At the top of **What it is**, under the object's name, is the **Verdict** on it — `✗ Stuck`, `✓ Expected`, or
 a quiet `? Unknown` — with the reason under it, in the same colours the chain on the left uses. Most objects
 in a heap dump are `Unknown`, which is why that one is drawn small: the two that mean something are the ones
-worth seeing across the room. This is the same answer a LeakCanary leak trace prints as `Leaking: YES`, `NO`
-and `UNKNOWN`, said about the object rather than about the leak — an object *leaked*, and a leak is the
-reference still holding it.
+worth seeing across the room.
 
-The reason is the whole of the answer, because half of these are about another object: an activity is red
-because its own `mDestroyed` is true, and the view under it is red because the activity is. `Activity↑
-leaked` is the chain saying so.
+`Stuck` says the object should be gone and something is holding it. `Expected` says its being in memory is
+legitimate at this point in the app's life. It is the same answer a LeakCanary leak trace prints as
+`Leaking: YES`, `NO` and `UNKNOWN`, in words that stop short of calling the object the leak — because
+**the leak is the faulty reference**, the one that should have been cleared, and everything under it is stuck
+by that single mistake. An object nothing reaches any more is `Stuck` as well: it was expected to be gone,
+and only the garbage collector not having run keeps it here. The verdict means the same thing everywhere.
 
-**The pencil beside it** overrules it. Pick one of the three statuses, type why, and **Set the status**:
+The reason is the rest of the answer, because half of these are about another object: an activity is red
+because its own `mDestroyed` is true, and the view under it is red because the activity is. `Activity↑ is
+stuck` is the chain saying so — and it is also how you find the faulty reference, which is the step between
+the last `Expected` object and the first `Stuck` one.
+
+**The pencil beside it** overrules the verdict. Pick one of the three, type why, and **Set the verdict**:
 
 * **Your answer wins**, whatever the inspectors said. Overruling is the point — an inspector reads a field,
   you read the code, and a cache that is meant to hold what it holds is not something a field can say.
-* **The reason is required.** A status with no reason is one nobody who reads your heap dump next — a
-  colleague, an agent, you in a month — can check, and one of those makes every other status in it worth
+* **The reason is required.** A verdict with no reason is one nobody who reads your heap dump next — a
+  colleague, an agent, you in a month — can check, and one of those makes every other verdict in it worth
   less. What you overruled is kept beside your reason rather than thrown away.
 * **It reads as yours**, wherever it appears: `set by hand — the cache is bounded, this is fine`, in the
   panel and on every chain that runs through the object.
-* **Everything a leaked object holds has leaked too, and everything holding a needed one is needed too**, so
-  a verdict you set changes what the objects around it read as. Which is why setting one is usually enough to
-  make a whole chain make sense.
+* **Everything a stuck object holds is stuck too, and everything holding an expected one is expected too**,
+  so a verdict you set changes what the objects around it read as. Which is why setting one is usually enough
+  to make a whole chain make sense.
 * **The pencil again** on an object you have already decided about, and **Take it off** to hand it back to
   the heap dump.
 
 Because a verdict propagates along the chain, two of them can contradict each other: an object marked as
-leaked, holding one marked as needed, cannot both be read off the chain between them. When what you are setting does that, **the window lists every status it disagrees with before writing
-anything** — what the object is, which side of yours it is on, the reason it was given, and what it would
-become. **Keep this and flip those** keeps yours and sets them to the opposite status, with what they said
-kept as part of the new reason; **Undo** leaves the heap dump exactly as it was. Nothing is written until you
-pick one.
+stuck, holding one marked as expected, cannot both be read off the chain between them. When what you are
+setting does that, **the window lists every verdict it disagrees with before writing anything** — what the
+object is, which side of yours it is on, the reason it was given, and what it would become. **Keep this and
+flip those** keeps yours and sets them to the opposite verdict, with what they said kept as part of the new
+reason; **Undo** leaves the heap dump exactly as it was. Nothing is written until you pick one.
 
-The statuses live in `~/.shark-explorer/leak-statuses`, one tab separated file per heap dump, with the columns
+The verdicts live in `~/.shark-explorer/leak-statuses`, one tab separated file per heap dump, with the columns
 named at the top — so they can be read, edited, diffed or pasted into an issue without this app, and they are
 there again the next time you open that dump.
 
-**The Leaks screen follows what you set**, because a status changes which objects are leaks and not only how
-one of them reads: marking something as leaked makes it a leak, and whatever it holds stops being one — it is
-only still in memory because of the object you named, and that is the thing to fix. Marking a leak as needed
-takes it off the list. The one thing this costs is that a leak's
-fingerprint matches the one LeakCanary reports only while nothing has been set by hand, since the fingerprint
-is the stretch of chain your status has just moved.
+**The Leaks screen follows what you set**, because a verdict changes which objects are leaks and not only how
+one of them reads: marking something as stuck makes it a leak, and whatever it holds stops being one — it is
+only still in memory because of the object you named, and that is the thing to fix. Marking a leak as
+expected takes it off the list. The one thing this costs is that a leak's fingerprint matches the one
+LeakCanary reports only while nothing has been set by hand, since the fingerprint is the stretch of chain your
+verdict has just moved.
 
 ## Reporting a problem
 

shark/shark-explorer/AGENTS.md

@@ -67,7 +67,14 @@ found, and the search for every way an object is held runs for the object clicke
 question the panels ask has to be measured before it goes in the hover path — `notes/decisions.md` has the
 numbers on the biggest dump in the repo, including how long a chain gets there.
 
-## A leaking status set by hand is an argument to every read, never state of the tree
+## A verdict set by hand is an argument to every read, never state of the tree
+
+**The window says `Verdict`, `Stuck`, `Expected` and "faulty reference"; the code says `LeakStatus`,
+`LEAKING`, `NOT_LEAKING` and `suspectPath`.** That's deliberate — the identifiers match
+`shark.LeakTraceObject.LeakingStatus` because they have to agree with Shark, and the words on screen
+deliberately avoid "leak" on an object, since a leak is one faulty reference and calling everything under it
+leaking points readers at the wrong thing. `LeakStatus.statusText` is the only place the two meet, so change
+a word there and nowhere else. `notes/decisions.md` has why each word won.
 
 Someone reading a heap dump can overrule what the inspectors made of an object, and the statuses they set
 are a `LeakStatusOverrides` **passed into every question whose answer they change** — `summarize`,

shark/shark-explorer/notes/decisions.md

@@ -841,29 +841,52 @@ a chain reads them here for free.
 `Shallow` beside it. It is the one line of the panel that is a judgement rather than a measurement, which is
 also what says the pencil beside it is allowed to disagree with it.
 
-**"Leaking" and "Not leaking" became "Leaked" and "Needed"**, `Unknown` staying `Unknown`. LeakCanary's leak
-traces say `Leaking: YES / NO / UNKNOWN`, and matching them was the case for keeping the old words — but
-calling an *object* leaking reads as that object leaking something as easily as being the thing left behind,
-and this repo's own rule is that a leak is a reference rather than an object. `Leaked` is that rule in the
-tense: the object leaked, and the leak is the reference still holding it. `Needed` is what an inspector
-actually recognizes — something still needs this object.
-
-The first attempt at those two was `Shouldn't be here` and `Meant to be here`, taken from the module's own
-prose, and it was rejected on sight for the reason a status has to be read a dozen times down one chain:
-**a status is a label, not a sentence.** The header carries the question so the labels don't have to, which
-is also why they can be one word each. One `LeakStatus.statusText` is where they live, so the chain, the
-panel, the dialog, the checkbox that shades them over the map and the reasons propagated along a chain
-(`Activity↓ is needed`) all say the same thing. The identifiers didn't move: `LeakStatus`, `LEAKING`,
-`leakStatusesOf` stay Shark's names, because the code is where matching
+**"Leaking" and "Not leaking" became `Stuck` and `Expected`**, `Unknown` staying `Unknown`, and **no word
+built on "leak" is allowed on an object**. A leak is one faulty reference that should have been cleared, and
+everything under it is retained by that one mistake — so `Leaking` or `Leaked` on twenty objects points a
+reader at the twenty rather than at the one thing to fix. `Stuck` names the object's situation without
+accusing it, and it is the only candidate that asks a question rather than closing one: something is holding
+this, what? `Expected` says its presence in memory is legitimate at this point in the app's life. The pair is
+deliberately not antonyms — an object in use can't be collected either, so the good side has to answer a
+different question than "can it leave".
+
+**No other analyser has a verdict like this**, so there were no words to borrow. Checked: JProfiler
+classifies objects by reference type (strongly referenced, retained by soft references) and by age (`Mark
+Heap`, then "new" and "old" objects); YourKit by reachability scope (strong, softly, weakly reachable,
+unreachable, pending finalization); Eclipse MAT names places rather than objects (*leak suspect*,
+*accumulation point*, *keep-alive path*); dotMemory has *key retention paths*. None labels an object leaking,
+because none has watched objects or framework inspectors to do it with — they rank by size and leave the
+judgement to the reader. What they do share is the frame: JProfiler asks whether objects "are still
+legitimately on the heap or if a **faulty reference** keeps them alive", which is where the name for the
+culprit edge comes from, and YourKit defines a leak as objects "not needed anymore according to the
+application logic".
+
+Two attempts came before this one. `Shouldn't be here` / `Meant to be here` was rejected on sight —
+**a verdict is a label, not a sentence**, since it is read a dozen times down one chain. `Leaked` / `Needed`
+was rejected for the misdirection above. One `LeakStatus.statusText` is where the words live, so the chain,
+the panel, the dialog, the checkbox that shades them over the map and the reasons propagated along a chain
+(`Activity↓ is expected`, `Activity↑ is stuck`) all say the same thing. The identifiers didn't move:
+`LeakStatus`, `LEAKING`, `leakStatusesOf` stay Shark's names, because the code is where matching
 `shark.LeakTraceObject.LeakingStatus` matters.
 
+**The verdict means the same thing on an unreachable object.** A watched object nothing reaches any more is
+`Stuck` like any other, even though what keeps it is the collector not having run rather than a faulty
+reference: it was expected to be gone. Where it sits on that scale is what the leaks screen's `Unreachable`
+section is for, and a fourth value would have made the verdict mean something different in one corner of the
+window.
+
+**"Faulty reference" is the name for the culprit**, the reference between the last `Expected` object and the
+first `Stuck` one, which is what `LeakGroup.suspectPath` starts at and what the leaks screen names each row
+after. Only prose so far — nothing on a chain marks that step yet, and marking it is the change that would
+actually put a reader's eye on the reference rather than on the objects.
+
 **A pencil, left of the status, rather than a "Set by hand…" button.** It is what changes the answer, so it
 belongs where the eye already is, and a text button pushed the reason onto a second line of a 320dp panel.
 Disabled until the statuses have been read off disk, which is the same rule the button had.
 
 **From the last step of the chain when there is one**, and from the object's own reading until the walk up to
 the GC roots lands, since the chain's answer is the one with the objects above and below taken into account.
-So the panel can say `Unknown` for a beat and then say `Leaked` — the panes filling in, not the window
+So the panel can say `Unknown` for a beat and then say `Stuck` — the panes filling in, not the window
 changing its mind. Nothing at all for the tab a window opens with: the whole heap dump is no
 object of it, and there is nothing to inspect or decide about.
 

shark/shark-explorer/shark-explorer-app/src/main/java/shark/explorer/app/HeapDumpExplorer.kt

@@ -212,7 +212,7 @@ internal fun HeapDumpExplorer(
    * From the last step of the chain when there is one, because that is the status with everything above and
    * below the object taken into account, and from the object's own reading until the walk up to the GC roots
    * lands — or for good, for an object nothing reaches. So this can say `Unknown` for a beat and then say
-   * `Leaked`, which is the panes filling in rather than the window changing its mind.
+   * `Stuck`, which is the panes filling in rather than the window changing its mind.
    *
    * Nothing for the whole heap dump, which is no object of it: there is nothing to inspect and nothing to
    * decide about.