Spec 001 T046: the figures step

specs/001-pathway-pdfs/contracts/cli.md

@@ -17,7 +17,7 @@ contracts/figures.md).
 | `--out`                              |                   | the folder written (contracts/figures.md)                                                                                                                            |
 | `--parallel`                         |                   | figures asked at once; default 2, the service's own default; set it to the service's `RENDER_CONCURRENCY`                                                            |
 | `--timeout`                          |                   | seconds the client waits for each attempt at a figure, and for each health or release read; default 60; above the render service's own timeout (contracts/render.md) |
-| `--report`                           |                   | where its run report is written, as JSON                                                                                                                             |
+| `--report`                           |                   | where its run report is written, as JSON; a file there already is refused (exit 2)                                                                                   |
 
 - **Which figures:** the events' Figure rules (data-model.md), from the graph and the
   EHLD summary, the same code `book` uses, so the folder holds exactly what the book
@@ -29,17 +29,25 @@ contracts/figures.md).
   must answer the graph's release (`GET /data/database/version`), the graph must carry a
   `DBInfo` checksum, and the render service's health answer a `build` other than
   `unknown` and `files: local` (contracts/render.md), or the run is refused before anything is drawn
-  (exit 2). What this cannot see is in contracts/figures.md.
+  (exit 2). Both services are probed before the preflight, so one down is said at once, and
+  read again after it for the folder's fingerprint; the preflight asks for no figure. What
+  this cannot see is in contracts/figures.md.
 - **One run, one folder:** `--out` must be empty or absent (exit 2 otherwise); a
   stopped run is not resumed. The manifest (contracts/figures.md) records the folder's
   fingerprint and what each file draws.
 - **Exit 0:** every figure is in the folder. **Exit 1:** a preflight fault
   (`missing-file`, `uncovered-character`, `bad-file`), a label fault after drawing, or a figure that
   could not be drawn, each named by stable identifier or file name. **Exit 2:** bad
-  arguments; the render or content service unreachable at the start; another release
+  arguments; a `--report` file that exists already (the earlier run's report kept, and none
+  written); the render or content service unreachable at the start; another release
   at `--content`; no graph checksum, no render `build`, or a render service not reading local files; or an `--out` that is not
   empty. A `build` or content release that changes during the run, a render or content
   service that stops answering, or the breaker, is exit 1 (contracts/figures.md).
+  Any other error (the graph failing during the checks, a file that cannot be written) is
+  exit 2, its error on stderr, the figures' own faults so far printed, the run stopped and
+  its report written. The report is written however the run ends but two: a signal, and a
+  `--report` refused; one that cannot be written is said on stderr, and the run keeps its
+  exit. The output's lines and the report are in contracts/figures.md.
 
 ## `pdf-export book`
 

specs/001-pathway-pdfs/contracts/figures.md

@@ -65,8 +65,8 @@ What `pdf-export figures` writes and `pdf-export book` reads (SC-010, research R
   but for `ancestor`).
 - **A deployment changed, a service gone, or the breaker tripped, during a run** stops it
   at once with exit 1 and no `complete` line.
-  Figures still being drawn when it stops get no line. The report is written either way,
-  naming the reason it stopped and each figure's own fault so far.
+  Figures still being drawn when it stops get no line. The report is written either way
+  (not on a signal), naming the reason it stopped and each figure's own fault so far.
 - **What the fingerprint cannot see** (research R10):
   - the render service's `build` hashes its own code, not the website's built page it
     loads, which is what draws;
@@ -102,6 +102,19 @@ What `pdf-export figures` writes and `pdf-export book` reads (SC-010, research R
   holding no names, only stable identifiers, kinds, times and counts. Any other file
   is ignored, so a folder drawn for a release can be read again by a book made from the
   same graph.
+- **The run report** (`--report`, JSON; T046), written beside its name and moved into
+  place, its folder made if need be, however the run ends but on a signal; a `--report`
+  that exists already is refused (exit 2) and no report is written, so an earlier run's
+  is never replaced; a report that cannot be written is said on stderr, the run keeping
+  its exit. Its fields: `release`
+  (the fingerprint, as far as it was read), `refused` (why the run was refused before
+  drawing, exit 2), `preflight` (its faults, exit 1), `figures` (for each kind: `needed`,
+  `drawn` by the render service, with `totalMs` and `maxMs`, retries included, and
+  `written`, in the folder with its line), `missing` (each figure's own fault, by `stId`,
+  `cause` and `detail`), `stopped` (`reason`: `deployment-changed`,
+  `deployment-unanswered`, `breaker-unanswered`, `breaker-silent` or `error`, and its
+  `detail`), `complete` and `elapsedMs`. On standard output, one `fault <fault>` line for
+  each preflight fault and `fault missing-figure <stId> <cause>` for each figure's own.
 - **A figure that could not be drawn** has no file and no line: `figures` draws the rest
   (unless the run stops at once, above),
   exits 1 with no `complete` line, and the book refuses the folder.