Spec
The contracts that two HelioSoftware tools depend on, written down once, with checksums so a copy that drifts is caught.
Contracts
| Contract | Version | Producer | Read by | Files |
|---|---|---|---|---|
| Checksums | 1 | this folder | everything below, and the site check that runs on every change | SHA256SUMS, spec_sums.py |
| Drift check | 1 | this folder | every repository that keeps a copy of a file from here | check_spec.py |
| Attic convention | 1 | this folder | every HelioSoftware repository: where retired files, branches and folders are recorded, and how to restore them | attic.md |
| Em-dash guard | 1 | this folder | CI in the Website, sunback and the store (vendored copies) | tools/no_em_dash.py |
| Short links | 1 | this folder (tools/check_site.py --write-shortlinks) |
the site check, offline and live | shortlinks.json |
| Agent preamble | 1 | this folder | every HelioSoftware repository's agent guide (CLAUDE.md or AGENTS.md), as a hash-stamped copy that check_spec.py verifies |
agent-preamble.md |
| RHEF conventions | v1 | this folder | every RHEF implementation, and anyone comparing two of them | rhef/conventions.md |
| RHEF test vectors | bundle 1.0.0 | generated from the reference implementation | the conformance tests of each implementation | rhef/vectors.json, rhef/golden/ |
| Release feed | 1 | this folder (heliosoftware/feed/append_record.py) |
the hub, the product pages, What's new and the release scripts of each product | release-feed.md |
| Imagery contract | v1 | sunback, aws_lambda/video_builder |
gilly.space/sun.html and the wall page, Heliogram, the Heliogram image mirror | CONTRACT.md in the producer repository, with the schemas and the dated fixtures beside it |
Using it from another repository
Keep a copy of this folder next to your checkout and point the check at it. The check reads the marker a copied file carries and says whether the copy still matches its source.
export HELIOSOFTWARE_SPEC_DIR=~/vscode/Website/heliosoftware/spec
python3 check_spec.py CLAUDE.md
python3 spec_sums.py --checkTwo markers are understood. A copied block of text sits between
<!-- heliosoftware-preamble v1 sha256=<hex> --> and
<!-- /heliosoftware-preamble -->. A copied file starts, on line 1 or on line 2 after a
shebang, with # heliosoftware-vendored: <label>:<path> sha256=<hex>
(// or ; in other comment syntaxes). The hash is of the file with that one line
removed. Exit codes: 0 all copies match, 1 a copy has drifted, 2 a file carries neither marker.
Rules
- Additive only. A contract that other software reads gets a new version beside the old one; an old version stays where it is.
- Every file in this folder is listed with its checksum in SHA256SUMS.
python3 spec_sums.py --writeis the only thing that writes that file. - RHEF output is a visualization, not a calibrated radiance.