What does "verified" actually mean in your stack?

The term "verified" in a codebase often has two distinct meanings, which can lead to confusion and errors. One meaning refers to a proven fact, such as a cryptographic signature that has been checked and confirmed as true. This type of verification is based on solid mathematical principles, where the result is either accurate or the underlying math has failed.

On the other hand, "verified" can also imply something inferred or estimated, like a judgement made by heuristics or a fingerprint that appears normal. This kind of verification is subjective and can be easily manipulated by a clever adversary. When "verified" is used interchangeably for both interpretations, downstream systems can make incorrect decisions. For example, a system might refuse legitimate customers based on an assumption, while the code itself appears to have verified the information.

To mitigate this, the author recommends maintaining a separate boolean field that only indicates whether a piece of information has been cryptographically verified. All other cases should be stored in a different field, such as a score or a set of signals, clearly marking them as opinions rather than certainties. This approach prevents the mixing of mathematical certainty with subjective judgments, reducing the likelihood of errors.

The same principle can be applied to other similar terms, like "is_bot" or "is_fraud," which might sound like definitive facts but are really estimates. By using suffixes like "_proven" or "_likely," the code becomes more honest and easier to understand, even as the codebase evolves over time and multiple engineers work on it.