dtourolle
84fade99ec
docs/ had 26 developer documents flat beside the manual, and the two audiences are very differently sized: most readers want the manual and the gesture reference, a few want the register, the designs and the measurements. The manual and gestures.md stay at the top; everything for someone changing the code moves to docs/dev/, and the two documents that name their own successors — the v0.1 milestone and the UI-refinement plan — go to docs/dev/archive/ rather than being deleted, since both are still cited. docs/README.md is the index, users first. Every reference follows: code comments, Cargo manifests, the workflows, the pre-commit hook, the bench and traceability tools (which locate the repo root by docs/dev/requirements.md now), packaging, the Docker READMEs, CLAUDE.md, CONTRIBUTING.md and the README. The matrix links one level deeper and is regenerated. Links out of the moved documents into the tree gain a level; a link checker over every Markdown file finds none broken.
114 lines
4.9 KiB
JSON
114 lines
4.9 KiB
JSON
{
|
|
"_readme": [
|
|
"The committed numbers for DarkRoom's benchmark suite (docs/requirements.md §8).",
|
|
"Produced and checked by `cargo run --release -p dr-bench`; docs/benchmarks.md explains each metric.",
|
|
"",
|
|
"Two gates, and they are not the same gate. `budget` is the requirement's own threshold and never moves.",
|
|
"`recorded` is what the reference desktop last measured, and a run that drifts past `tolerance` beyond it",
|
|
"fails the build even while still inside the budget — which is how most performance rot actually arrives.",
|
|
"",
|
|
"`recorded` is null on every metric because nobody has run the suite yet. That is deliberate: writing",
|
|
"plausible-looking figures here would make every later comparison a comparison against a guess. Run",
|
|
"`cargo run --release -p dr-bench -- record --reference` on the reference desktop and commit the diff.",
|
|
"Until then the budget gate works and the regression gate says, in the report, that it cannot.",
|
|
"",
|
|
"`machine_sensitive` says whether a budget is a statement about a machine as much as about the code.",
|
|
"Those budgets are asserted only under --reference: §8 names the reference desktop, and a two-core CI",
|
|
"container cannot speak to a target written for twenty-four threads. Asserting one there would produce a",
|
|
"red gate everybody learns to ignore, which is the trap core/dr-gpu/tests/frame_budget.rs already avoids.",
|
|
"",
|
|
"Several metrics carry a requirement ID with a qualifier. Read those literally. NFR-P7's budget here is",
|
|
"checked against the encode half of an export only — no GPU render is in the figure — so it can fail the",
|
|
"requirement and cannot pass it, and no TRACES tag claims otherwise. NFR-P8 has no budget at all yet,",
|
|
"because nobody has decided how much of its 500 MB belongs to the catalog layer; this records the number",
|
|
"that decision needs."
|
|
],
|
|
"tolerance": 0.15,
|
|
"recorded_on": null,
|
|
"recorded_at_unix": null,
|
|
"fixture": null,
|
|
"metrics": {
|
|
"catalog_filtered_ms": {
|
|
"requirement": "FR-CAT-6",
|
|
"what": "Count plus first window under a rating filter, which compiles to a correlated subquery over versions.",
|
|
"unit": "ms",
|
|
"direction": "lower_is_better",
|
|
"machine_sensitive": true,
|
|
"budget": null,
|
|
"recorded": null
|
|
},
|
|
"catalog_idle_rss_mb": {
|
|
"requirement": "NFR-P8 (the catalog layer's share only — no toolkit, no adapter, no decode cache)",
|
|
"what": "Resident memory of a process that opened the 50k catalog and scrolled ten thousand rows.",
|
|
"unit": "MB",
|
|
"direction": "lower_is_better",
|
|
"machine_sensitive": false,
|
|
"budget": null,
|
|
"recorded": null
|
|
},
|
|
"catalog_open_ms": {
|
|
"requirement": "NFR-P1",
|
|
"what": "Catalog::open plus the count, first window and timeline the grid cannot paint without.",
|
|
"unit": "ms",
|
|
"direction": "lower_is_better",
|
|
"machine_sensitive": false,
|
|
"budget": 2000.0,
|
|
"recorded": null
|
|
},
|
|
"catalog_open_warm_ms": {
|
|
"requirement": "NFR-P1",
|
|
"what": "The same four calls on a second connection, with SQLite's page cache already warm.",
|
|
"unit": "ms",
|
|
"direction": "lower_is_better",
|
|
"machine_sensitive": false,
|
|
"budget": 2000.0,
|
|
"recorded": null
|
|
},
|
|
"catalog_window_p99_ms": {
|
|
"requirement": "FR-CAT-4",
|
|
"what": "One 400-row grid window at a random offset, p99 of one hundred.",
|
|
"unit": "ms",
|
|
"direction": "lower_is_better",
|
|
"machine_sensitive": true,
|
|
"budget": null,
|
|
"recorded": null
|
|
},
|
|
"export_24mp_long_edge_2048_ms": {
|
|
"requirement": "FR-EXP-3",
|
|
"what": "The web export: resample a 24 MP frame to a 2048 px long edge, sharpen, encode. p99 of five.",
|
|
"unit": "ms",
|
|
"direction": "lower_is_better",
|
|
"machine_sensitive": true,
|
|
"budget": null,
|
|
"recorded": null
|
|
},
|
|
"export_24mp_original_ms": {
|
|
"requirement": "NFR-P7 (the encode half only — the GPU render is not in this figure)",
|
|
"what": "Resample, output-sharpen and JPEG-encode a 24 MP frame at source size. p99 of five.",
|
|
"unit": "ms",
|
|
"direction": "lower_is_better",
|
|
"machine_sensitive": true,
|
|
"budget": 2000.0,
|
|
"recorded": null
|
|
},
|
|
"thumbnail_per_image_p99_ms": {
|
|
"requirement": "NFR-P3",
|
|
"what": "One thumbnail on its own lane: decode the preview, downscale, orient, encode. p99.",
|
|
"unit": "ms",
|
|
"direction": "lower_is_better",
|
|
"machine_sensitive": true,
|
|
"budget": null,
|
|
"recorded": null
|
|
},
|
|
"thumbnail_throughput_ips": {
|
|
"requirement": "NFR-P3",
|
|
"what": "Whole-sweep throughput: 1200 thumbnails through the sweep's chunk-and-lane shape, wall clock.",
|
|
"unit": "img/s",
|
|
"direction": "higher_is_better",
|
|
"machine_sensitive": true,
|
|
"budget": 100.0,
|
|
"recorded": null
|
|
}
|
|
}
|
|
}
|