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 |
| Colour tables | 1 | HelioFITS (tools/colormaps/gen_colormaps.py --json-out) |
anyone comparing the colour tables of two products, with tools/diff_luts.py |
colormaps/, tools/diff_luts.py |
| Rainbow recipe | description, 2026-10-05 | this folder | sunback and the My Heliogram store, which both build the three-channel picture | rainbow-recipe.md |
| Versioning | 1 | this folder | every product's release scripts and the shared release gate: one declared version source per product, the tag and changelog convention | versioning.md |
| Publish handshake | 1 | this folder | each product's publish script: which files it may write into this site; the site owns every page | publish-handshake.md |
| Family look | 1 | this folder | gilly.space stylesheets now; the store stylesheets (sunback_webapp) once Gilly approves the colour change. tools/tokens.py --check fails on drift |
tokens.json, tools/tokens.py, icon-family.md |
| Provenance | 1 | this folder | every product that exports an image, movie or sidecar: the fields, where PNG, FITS and MP4 keep them, and the credit and disclaimer text. tools/check_provenance.py reads a file back |
provenance.md, attribution.json, tools/check_provenance.py |
| Processing record | 1.0 | this folder | every product that exports an image, movie or data file, beside the provenance stamp: each layer's sources by SHA-256, its steps in order, and the producer's scene for a rebuild. Heliad reads it back | processing-record.md, hfrecord-1.schema.json, examples/ |
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.