|
| 1 | +{ |
| 2 | + "contract_version": 1, |
| 3 | + "title": "pyg-bench published docs numbers", |
| 4 | + "summary": [ |
| 5 | + "The boundary between this repository and the pygraphistry docs. pyg-bench MEASURES and", |
| 6 | + "PUBLISHES; pygraphistry pretty-prints. Everything a consumer is allowed to assume about", |
| 7 | + "published/docs-numbers.json is written down here, checked on the producer side before the", |
| 8 | + "artifact is written, and re-verified independently on the consumer side before it renders.", |
| 9 | + "Two independent implementations of these rules is the point: a shared library would fail", |
| 10 | + "the same way on both sides of the boundary." |
| 11 | + ], |
| 12 | + "artifact_path": "published/docs-numbers.json", |
| 13 | + "top_level_required": [ |
| 14 | + "contract_version", |
| 15 | + "schema_version", |
| 16 | + "generated_by", |
| 17 | + "generated_at", |
| 18 | + "policy", |
| 19 | + "runs", |
| 20 | + "cells" |
| 21 | + ], |
| 22 | + "policy_required": ["max_age_days", "managed_docs"], |
| 23 | + "run_required": [ |
| 24 | + "measured_at", |
| 25 | + "host", |
| 26 | + "perf_lock_held", |
| 27 | + "quiet_host", |
| 28 | + "reps", |
| 29 | + "pygraphistry_commit", |
| 30 | + "pyg_bench_commit", |
| 31 | + "runtime", |
| 32 | + "dataset", |
| 33 | + "artifact", |
| 34 | + "row_validation" |
| 35 | + ], |
| 36 | + "cell_required": [ |
| 37 | + "run", |
| 38 | + "workload", |
| 39 | + "engine", |
| 40 | + "value", |
| 41 | + "unit", |
| 42 | + "decimals", |
| 43 | + "status", |
| 44 | + "comparison_allowed", |
| 45 | + "board_quotable", |
| 46 | + "disclosures" |
| 47 | + ], |
| 48 | + "cell_status": ["ok", "partial", "adapter_workaround", "result_mismatch"], |
| 49 | + "cell_unit": ["ms", "s", "x"], |
| 50 | + "key_pattern": "^[a-z0-9][a-z0-9_]*(\\.[a-z0-9][a-z0-9_]*)+$", |
| 51 | + "date_pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", |
| 52 | + "max_decimals": 4, |
| 53 | + "invariants": [ |
| 54 | + { |
| 55 | + "id": "cell_names_a_known_run", |
| 56 | + "rule": "every cell.run must be a key of runs", |
| 57 | + "why": "a number whose provenance record is absent is an unprovenanced number" |
| 58 | + }, |
| 59 | + { |
| 60 | + "id": "quotable_implies_comparable", |
| 61 | + "rule": "board_quotable implies comparison_allowed", |
| 62 | + "why": "a diagnostic-only figure must never reach a board" |
| 63 | + }, |
| 64 | + { |
| 65 | + "id": "quotable_implies_ok", |
| 66 | + "rule": "board_quotable implies status == 'ok'", |
| 67 | + "why": "partial / adapter_workaround / result_mismatch cells are not results" |
| 68 | + }, |
| 69 | + { |
| 70 | + "id": "caveat_travels_with_the_number", |
| 71 | + "rule": "status != 'ok' or comparison_allowed is false implies disclosures is non-empty", |
| 72 | + "why": "a bare ratio without its asterisk launders the caveat" |
| 73 | + }, |
| 74 | + { |
| 75 | + "id": "ratios_are_comparisons", |
| 76 | + "rule": "unit 'x' implies comparison_allowed", |
| 77 | + "why": "a ratio between two numbers that were never established as comparable is not a speedup" |
| 78 | + }, |
| 79 | + { |
| 80 | + "id": "value_is_rounded_as_published", |
| 81 | + "rule": "value == round(value, decimals), value is finite and >= 0, 0 <= decimals <= max_decimals", |
| 82 | + "why": "the consumer prints value verbatim; rounding must not happen at render time" |
| 83 | + }, |
| 84 | + { |
| 85 | + "id": "engine_is_named", |
| 86 | + "rule": "cell.engine is a non-empty string", |
| 87 | + "why": "pandas and polars are not interchangeable and the reader must be told which one ran" |
| 88 | + }, |
| 89 | + { |
| 90 | + "id": "measurement_is_dated", |
| 91 | + "rule": "run.measured_at matches date_pattern", |
| 92 | + "why": "staleness is checked against the MEASUREMENT date, not the export date" |
| 93 | + } |
| 94 | + ], |
| 95 | + "consumer_obligations": [ |
| 96 | + "Refuse to render a key the artifact does not contain — a missing number is a build failure, never blank text.", |
| 97 | + "Refuse to render a cell whose run.measured_at is older than policy.max_age_days.", |
| 98 | + "Refuse to render a non-board_quotable cell as a bare number; it may appear only through a role that labels it diagnostic-only.", |
| 99 | + "Render every referenced cell's disclosures and its run's provenance on the same page.", |
| 100 | + "Re-verify every invariant above before rendering, with an implementation that does not import this repository." |
| 101 | + ] |
| 102 | +} |
0 commit comments