What it does for you
superstack lets a frame or a sound made by one engine be checked against another, byte for byte. You copy one file for your language: Python, JavaScript or C++. It hashes any scene the same way in all three, draws the same random numbers from the same seed string, keeps time on one integer clock, and seals a receipt that says whether your bytes equal the reference and whether they fall within tolerance. Every receipt also lists what it does not prove.
- Same bytes in three languagesCanonical JSON v2 has one number form that Python, JavaScript and C++ all write.
- Same randomness from a stringA seed string goes through xmur3 into mulberry32, so every language draws the same stream.
- Two verdicts, kept apartIdentity is MATCH or DRIFT. Tolerance is verified, refuted or unverifiable.
- Conformance you can run383 vector checks per language, and 59 paired mutations that each break one rule.
Source: README.md at 7587e22 (release 0.2.0)
Watch
Video walkthrough: coming with the next release.
How it works, one step at a time
Scroll, or use the step buttons. Every value below is output from the Python and JavaScript files at commit 7587e22, or from examples/run_all.py --ci, which CI runs on Linux and Windows.
- 01
One number form for every language
Hash a scene in Python and in JavaScript and you need the same bytes first.
canonicalsorts keys, writes compact UTF-8 and uses one number form:1.0becomes1and1e-7becomes0.0000001, which C++ writes the same way.Source: SPEC.md, section 3; superstack.py
- 02
A seed string, one stream everywhere
The seed rule turns a string into numbers: xmur3 hashes it and mulberry32 draws from it. The seed
folded-lightgives the same stream in each language, and its 32-bit value goes into the receipt.Source: SPEC.md, section 4
- 03
Time on one integer clock
Time is counted in flicks, 705,600,000 per second. Common frame and sample rates land on whole numbers: one sample at 48 kHz is 14,700 flicks and at 44.1 kHz is 16,000. Four samples at 48 kHz last 58,800 flicks, with no rounding.
Source: SPEC.md, section 5
- 04
Seal a receipt
Four float samples are quantised to 16-bit PCM and hashed.
make_receiptrecords the scene hash, the seed, the clock, the media description with its access settings (no autoplay, a reduced-sound mode) and the content hash, then seals the whole receipt with SHA-256.A
does_not_proveline is required: here, that a PCM hash says nothing about how a device plays the sound.Source: superstack.py,
make_receipt; SPEC.md, section 6 - 05
Verify, and what fails it
verify_receiptreturns a list of problems. A fresh receipt returns none. Change a field after sealing and the seal fails. Empty thedoes_not_provelist and that rule fails by name. Pick each case in the panel.Source: superstack.py,
verify_receipt - 06
The proof scene, with its controls
The examples render one scene and one sound through more than one engine and check each against its reference. A numpy port of raw-native gives the reference pixel hash,
0282ef9c, and the JavaScript sound path gives the reference PCM hash,692ead20.Three controls must fail, and they do: an AO radius of 1.5 where the scene says 2, one flipped byte, and one voice one sample late.
Source: examples/run_all.py; examples/README.md
Walkthrough
Install it, run it once, then use the main feature. Each command below is real, and so is its output.
Get it
Clone the repository. Python 3.11 or newer and Node 20 or newer; no install step.
$ git clone https://github.com/HarperZ9/superstack && cd superstackFirst run: the shared vectors
Run the same 383 checks in each language.
$ python tests/run_vectors.py python: 383/383 checks passed $ node tests/run_vectors.mjs javascript: 383/383 checks passedSeal a receipt
In Python, seal a receipt over quantized audio samples.
>>> ss.make_receipt(producer='my-synth', ..., content=ss.quantize_s16([0.0, 0.25, -0.25, 0.5])) schema superstack.receipt/1 scene_sha256 42fbae6d8011ad33... seed_rule xmur3-mulberry32/1 duration_flicks 58800 content_sha256 33b047ac8f974190... does_not_prove A PCM hash says nothing about how a device plays the sound. receipt_sha256 9b10693f6e0f65eb...The proof scene
Run every example with its controls.
$ python examples/run_all.py --ci pixels python MATCH verified sound sound-js-exact MATCH verified control wrong_ao_radius DRIFT refuted as expected control one_byte_flipped DRIFT verified as expected control sound_one_sample_late DRIFT refuted as expected examples: all expectations held
Output from superstack at 7587e22 on Windows with Python 3.12 and Node 25. The C++ runner was not built for this page; the README reports 383 checks for it too.
What it does not do
- A content hash proves the bytes. It says nothing about how a screen shows them or a device plays them, and each receipt says so in its own words.
- The proof observed equality on one workstation and on CI runners. It does not show equality across GPU vendors or drivers.
- The pixel reference's own certificate refutes its screen-space AO against its ray-traced AO on the proof view. The contract checks agreement between engines. Whether the reference is good is a separate question.
- Narration backends are never references. Their output is checked for tolerance only.
Source: README.md at 7587e22, "Evidence"; SPEC.md, section 8
Check what stuck
Answer each one in your head before you open it.
What does canonical JSON write for 1.0 and 1e-7?
1 and 0.0000001, in every language.
How many flicks are in one sample at 48 kHz?
14,700. A second is 705,600,000 flicks, chosen so common rates divide it evenly.
What are a receipt's two verdicts?
Identity, MATCH or DRIFT, and tolerance: verified, refuted or unverifiable.
One byte of a frame is flipped. Which verdicts does the control get?
DRIFT for identity and verified for tolerance: the bytes differ, but by one level on one pixel.