A golden vector is a recorded input and its expected output, committed to the repository and checked on every build. Ours cover the wire: given this payload, the contract produces exactly this shape with exactly this signature.
They are the least clever tests we have and they catch the most.
The failure mode nobody plans for
The vector file gets moved. Or the glob stops matching. Or a refactor renames the directory and the loader quietly finds nothing.
The suite runs. Zero vectors are checked. Every one of them passes.
This is worse than having no vectors, because now you have a green tick that means nothing and everyone has learned to trust it.
The guard
if (vectors.length === 0) {
throw new Error('verify-vectors: refusing to pass on an empty vector set');
}Four lines. It converts the most dangerous possible outcome — silent success — into a loud failure.
We have tripped it twice. Both times it was a path change nobody thought would matter, and both times the build stopped instead of shipping a contract nothing had verified.
Append-only
The other rule: vectors/wire-v1.json is append-only, enforced in review.
You cannot edit what v1 means. You can only add v2 and migrate consumers deliberately. It makes the file grow forever, which is fine — it is a few hundred kilobytes and it is the entire history of what we promised.
Dana Reyes
Staff Engineer
