Where in a run's results should a failing case's evidence be attached so a reader finds it without reopening the run?

## A results document is a tree, and evidence has an address A run's results nest naturally: the run, the suites inside it, the cases inside those, the attempts a case made, and sometimes the steps inside an attempt. Every piece of evidence a run produces belongs to exactly one of those nodes, and **attaching it to the wrong one is what turns a diagnosable failure into a re-run**. The default that hurts is dumping everything at run level: one destination full of files named by timestamp, one log covering the whole run. The evidence exists — that is not the problem. The problem is that finding the piece explaining *this* failing case means opening the run, matching timestamps by eye, and already knowing the harness's naming convention. The reader who most needs the evidence is usually the one least likely to have that knowledge. ## Which node owns which evidence | Node | What belongs on it | Why here | |---|---|---| | Run | Target identity, suite-wide configuration, total duration | It is equally true of everything below | | Suite | Setup that ran once for the whole group | It explains a whole group failing together | | Case | The case's stable identity, its derived status, links to its attempts | The unit a reader searches for | | Attempt | The outcome, the failure message, the captures produced that time | Two attempts produce different evidence | | Step | The step's outcome and the point where things diverged | Narrows the reader to a line | The rule is: **attach to the smallest node that owns it**. If a capture would be identical for every case in the group, it belongs to the group. If it exists only because *this* attempt did what it did, it belongs on that attempt. ## An attachment is a record, not a file lying nearby Three fields make the difference between evidence a reader can use and evidence a reader has to hunt for: - A **reference** — a locator recorded in the results that resolves to the artefact, relative to wherever the run's output was published rather than to a machine's disk. - A **kind** — what sort of thing it is, so a reader or a viewer can choose without opening it. Extensions are a guess: the same text file may be an interaction trail, a captured response body, or the harness's own diagnostics. - A **label** — a short human name, because a reader scanning a case with six attachments needs to know which one to open first. Three properties follow from writing it this way: 1. The results document reads on its own and still says what evidence exists, before anything is downloaded. 2. Evidence survives being republished elsewhere, because references resolve relative to the output rather than to a path that existed on one machine for one hour. 3. Nothing is orphaned by a rename, because attachments hang off the case's stable identity rather than off its display name. ## The attempt level, where most models leak When a case ran more than once inside a run, each attempt produced its own evidence. Two things go wrong, and both are common: - **Overwriting.** The second attempt writes over the first attempt's capture, because the destination name was derived from the case and not from the case *and* the attempt. The evidence for the only interesting outcome — the failing one — is gone by the time anyone looks. - **Flattening.** Every attempt's captures are attached to the case node, so a reader sees six files and cannot tell which run of the case produced which. The evidence is present and unusable. Both are fixed by the same change: the attempt is a node in the model, it carries its own outcome, and its captures hang off it. ## Placement when a run is spread across workers A suite split across parallel test workers produces several partial results documents that are merged afterwards, and placement decides whether that merge is trivial or lossy. If each worker writes into a shared flat destination keyed by display name, two workers running cases whose names coincide collide and one silently wins. If every reference is namespaced by the case's stable identity and its attempt index, the merge is a concatenation and nothing is lost. The same reasoning covers a case run against two different target configurations in one run. Those are two case results, not one, and each owns its own attempts and captures. Folding them onto a single case node produces a row whose attachments contradict each other and whose status has to pick a winner. ## A test for a placement scheme Take one failing case out of the results document, with the surrounding run removed, and hand it to someone who has never seen the suite. They should be able to say what failed and open the right piece of evidence first, without asking which destination to look in and without running anything. If the answer needs a naming convention nobody wrote down, the evidence is attached to the wrong node — or to no node at all.