Spec 001 T024: the book's preflight

ci/fixture/README.md

@@ -14,6 +14,7 @@ release 98's (every relationship has `order` and `stoichiometry`).
 | Case                                                                                                             | Where                                                                                       | For                                           |
 | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------- |
 | Release 98                                                                                                       | `DBInfo.releaseNumber`                                                                      | the introduction, the base of ids             |
+| A checksum beyond what a JavaScript number holds whole (2^53 + 1)                                                | `DBInfo.checksum`                                                                           | the figures' folder's fingerprint (T024)      |
 | Three human top-level pathways, ordered differently by id, by case and ignoring case                             | `beta pathway`, `Alpha pathway`, `Gamma pathway`                                            | FR-002's order                                |
 | A non-human top-level pathway                                                                                    | `Mouse pathway`                                                                             | `--species`                                   |
 | A subpathway with no diagram, under one with a diagram                                                           | `Alpha sub one`                                                                             | the ancestor's diagram with a selection       |
@@ -32,6 +33,7 @@ release 98's (every relationship has `order` and `stoichiometry`).
 | A disease, and one named exactly "disease"                                                                       | `Disease reaction`                                                                          | the "disease" exclusion                       |
 | A node that is not an event, with a stable id                                                                    | `Placeholder complex`                                                                       | 400 `not-an-event`                            |
 | Participants of each kind, in a complex, a set, a candidate set and a polymer, with identifiers (one an isoform) | `Reaction one`                                                                              | a reaction's own identifiers, for an analysis |
+| A compartment only a participant holds, named in no event's section                                              | `placeholder membrane`, of Reaction one's output                                            | FR-017 in the figures' names (T024)           |
 
 ## The release's files
 

ci/fixture/fixture.cypher

@@ -4,12 +4,13 @@
 // lists the case each item is here for. Load with: cypher-shell -d graph.db -f fixture.cypher
 CREATE INDEX fixture_dbId IF NOT EXISTS FOR (n:DatabaseObject) ON (n.dbId);
 CREATE INDEX fixture_stId IF NOT EXISTS FOR (n:DatabaseObject) ON (n.stId);
-CREATE (db:DatabaseObject:MetaDatabaseObject:DBInfo:Release {dbId: 90000001, displayName: '98 on 2026-09-18', name: 'reactome', releaseNumber: 98, releaseDate: '2026-09-18', schemaClass: 'DBInfo'})
+CREATE (db:DatabaseObject:MetaDatabaseObject:DBInfo:Release {dbId: 90000001, displayName: '98 on 2026-09-18', name: 'reactome', releaseNumber: 98, checksum: 9007199254740993, releaseDate: '2026-09-18', schemaClass: 'DBInfo'})
 CREATE (hsa:DatabaseObject:Taxon:Species {dbId: 90000002, displayName: 'Homo sapiens', name: ['Homo sapiens'], taxId: '9606', abbreviation: 'HSA', schemaClass: 'Species'})
 CREATE (mmu:DatabaseObject:Taxon:Species {dbId: 90000003, displayName: 'Mus musculus', name: ['Mus musculus'], taxId: '10090', abbreviation: 'MMU', schemaClass: 'Species'})
 CREATE (rno:DatabaseObject:Taxon:Species {dbId: 90000004, displayName: 'Rattus norvegicus', name: ['Rattus norvegicus'], taxId: '10116', abbreviation: 'RNO', schemaClass: 'Species'})
 CREATE (cyto:DatabaseObject:Compartment:GO_CellularComponent:GO_Term {dbId: 90000010, displayName: 'cytosol', name: 'cytosol', accession: '0000010', databaseName: 'GO', schemaClass: 'Compartment'})
 CREATE (nucl:DatabaseObject:Compartment:GO_CellularComponent:GO_Term {dbId: 90000011, displayName: 'nucleoplasm', name: 'nucleoplasm', accession: '0000011', databaseName: 'GO', schemaClass: 'Compartment'})
+CREATE (memb:DatabaseObject:Compartment:GO_CellularComponent:GO_Term {dbId: 90000014, displayName: 'placeholder membrane', name: 'placeholder membrane', accession: '0000014', databaseName: 'GO', schemaClass: 'Compartment'})
 CREATE (dis1:DatabaseObject:ExternalOntology:Disease {dbId: 90000012, displayName: 'placeholder infectious disease', name: ['placeholder infectious disease'], identifier: '0000001', databaseName: 'DOID', schemaClass: 'Disease'})
 CREATE (dis2:DatabaseObject:ExternalOntology:Disease {dbId: 90000013, displayName: 'disease', name: ['disease'], identifier: '4', databaseName: 'DOID', schemaClass: 'Disease'})
 CREATE (beta:DatabaseObject:Event:Pathway:Trackable:Deletable:TopLevelPathway {dbId: 90000100, stId: 'R-HSA-90000100', stIdVersion: 'R-HSA-90000100.1', displayName: 'beta pathway', name: ['beta pathway'], schemaClass: 'TopLevelPathway', speciesName: 'Homo sapiens', hasDiagram: true, hasEHLD: false, isInferred: false, isInDisease: false, releaseDate: '2026-09-18'})
@@ -144,6 +145,7 @@ CREATE (ewas5)-[:referenceEntity {order: 0, stoichiometry: 1}]->(ref5)
 CREATE (r1)-[:input {order: 2, stoichiometry: 1}]->(poly1)
 CREATE (poly1)-[:repeatedUnit {order: 0, stoichiometry: 1}]->(ewas6)
 CREATE (ewas6)-[:referenceEntity {order: 0, stoichiometry: 1}]->(ref6)
+CREATE (ewas1)-[:compartment {order: 0, stoichiometry: 1}]->(memb)
 CREATE (r1)-[:compartment {order: 0, stoichiometry: 1}]->(nucl)
 CREATE (r1)-[:compartment {order: 1, stoichiometry: 1}]->(cyto)
 CREATE (r3)-[:compartment {order: 0, stoichiometry: 1}]->(cyto)

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

@@ -1,6 +1,6 @@
 # Contract: the command line
 
-One executable, `pdf-export`, with five commands. Settings come from flags or from the
+One executable, `pdf-export`, with six commands. Settings come from flags or from the
 environment variables named beside them. A password never goes on the command line.
 
 ## `pdf-export figures`
@@ -34,7 +34,7 @@ contracts/figures.md).
   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`), a label fault after drawing, or a figure that
+  (`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
   at `--content`; no graph checksum, no render `build`, or a render service not reading local files; or an `--out` that is not
@@ -67,7 +67,8 @@ the figures already drawn by `figures`.
   hold) and the figures' files in `--figures`, and a file missing is a fault
   `missing-file <name>`. The folder must pass the checks contracts/figures.md lists under
   "What `book` checks": `incomplete-folder`, `no-checksum`, `stale-folder`,
-  `stale-summary` and `stale-figure <stId>`. A top-level pathway's name a file cannot
+  `stale-summary` and `stale-figure <stId>`. A diagram file that cannot be read as JSON is
+  a fault `bad-file <name>`. A top-level pathway's name a file cannot
   hold, or two equal ignoring case, is a fault `bad-file-name <stId>` (data-model Book).
   Any of these ends the step with exit 1 and no book written (Story 5,
   scenario 3). A character no font covers, after FR-017's substitutions, is a fault
@@ -76,7 +77,9 @@ the figures already drawn by `figures`.
   - **before any figure is read** (and by `figures`, before any is drawn), in the graph's texts the layout writes, in the names
     the figures label (every physical entity a reaction's figure draws: its inputs,
     outputs, catalysts and regulators; and their compartments, from the graph), and in
-    the labels of the diagram files the Figure rules choose to draw (`--files`; today an
+    the labels of the diagram files the Figure rules choose to draw (the `displayName`s
+    of their nodes, compartments, notes, shadows and links, and the `label`s of their
+    nodes' attachments, a modification's lettering) (`--files`; today an
     illustrated pathway's file is not among them, its figure being its EHLD, data-model
     Figure); a fault in a text names the event whose section holds it, one in a
     figure's names the first event in document order whose figure holds it, and one in
@@ -93,7 +96,32 @@ the figures already drawn by `figures`.
 - **Exit 1:** a fault from the preflight or FR-011. The report names each one by stable
   identifier or file name, never a person.
 - **Exit 2:** bad arguments; an `--out` that is not absent or empty, as for `figures`
-  (an old book is never replaced in place); or the graph cannot be reached at the start.
+  (an old book is never replaced in place); the graph cannot be reached at the start; or
+  any other error during the preflight, as `preflight` exits on one (below).
+
+## `pdf-export preflight`
+
+`book`'s preflight alone (T024), with `book`'s `--graph`, `--database`, `--files`,
+`--figures` (both required) and `--species`, so a release's inputs and figures' folder can
+be checked before the book is made. It prints one line per fault, `fault <fault>`, in the
+forms above (`missing-file <name>`, `incomplete-folder`, `no-checksum`,
+`stale-folder <folder's release>/<checksum> <graph's release>/<checksum>`, `stale-summary`,
+`stale-figure <stId>`, `bad-file-name <stId>`, `uncovered-character <code point> <stId>`,
+and `bad-file <name>` for a diagram file that cannot be read as JSON, whose labels are then
+not checked),
+each naming a stable identifier or a file, never a text or a person. A release file is named
+as in `--files` (`diagram/R-HSA-….json`), a figure's as in `--figures` (`R-HSA-….svg`).
+
+- **Exit 0:** no fault. **Exit 1:** at least one. **Exit 2:** bad arguments; the graph
+  cannot be reached at the start, or its address cannot be parsed (said within seconds:
+  that first read's retrying is bounded, the rest keep the driver's own); or any other
+  error during the checks (a graph that fails mid-run): the faults found before it are
+  printed first, then the error on stderr. The faults are kept check by check: those of
+  the check the error stopped are lost. Exit 1 always means faults, never an error.
+- A folder that is not whole, or not this graph's release or summary's, is refused as a
+  whole: its figures are then not checked one by one.
+- Without the EHLD summary the Figure rules cannot be followed: the one fault is
+  `missing-file ehld/svgsummary.txt`.
 
 ## `pdf-export check-book <folder>`
 

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

@@ -56,6 +56,13 @@ What `pdf-export figures` writes and `pdf-export book` reads (SC-010, research R
 
   - **Its last line, when every figure has its line:** `complete`, whose fingerprint
     fields equal the first line's.
+- **The lines' form** (T024, `src/preflight/folder.ts`, which T046 writes with): each a JSON
+  object with a `type`. The fingerprint and `complete`: `release` (a number), `checksum`
+  (the `DBInfo` checksum's decimal digits, a string, as a long can exceed what a JSON
+  reader's number holds whole), `summary` (`sha256:` and the hex digest of the summary
+  file's bytes), `content` (a number) and `build` (a string). A figure: `stId`, `kind`
+  (`diagram`, `ancestor`, `ehld` or `reaction`), `source` and `highlight` (sorted; empty
+  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,