The Card Must Not Overclaim

The trust section of the card was headed Verified claims.

Under that heading sat a handful of lines about a remote service an agent had just called: where it said it was running, what it said it was, which checks had passed on the way to it. Some of those lines had been checked by something we operate. Some of them were only what the remote service had said about itself, passed along with a caveat. The heading covered all of them with one word, and the word was wrong for half of them.

Nobody had lied. The data underneath was honest: every value carried its source. The overclaim was in the copy, the part of a trust surface that gets the least review because it looks like decoration. It is not decoration. On a card whose whole job is to tell a person what they can rely on, every word, every colour and every chip is a claim. And a claim on that card is only as good as the record that backs it.

One heading, then every word

The heading became Verifiable claims: these are the claims, and here is how far each one can be checked. That fixed the heading. It also raised an uncomfortable question about everything else on the card, so we applied the same test to every word: could the record back this?

That test changed more than we expected:

• “Checked”, not “proven”. A hop ran a check. It did not produce a proof. The difference matters to anyone who later has to defend the decision.
• “Declared”, not “self-reported”. Name the act, not the suspicion. “Self-reported” quietly tells the reader to distrust the value. “Declared” tells them exactly what happened: the service stated it, and nothing else stood behind it.
• “Declared”, not “attested”. We had a stronger word available and deliberately did not use it. “Attested” means a witness outside the service vouched for its configuration. We do not have that witness yet. So the word is reserved: it stays off the screen until the thing it names exists.
• “Origin location not verified”. No “yet”. “Not verified yet” promises a future the record cannot see.

None of these changes touched the data. The values on the wire stayed exactly as they were. What changed is the projection: the words a person reads are a rendering of the record, and that rendering is allowed to say less than the record, never more.

A grade for every value, named by who stands behind it

The word-by-word pass ended in a small vocabulary rather than a list of fixes. Every value on the card carries a grade, and each grade names who stands behind the value:

• witnessed: something we operate saw it directly;
• computed: we derived it from values we hold;
• implied: an arrival implies that an earlier control passed, though nobody recorded that control directly;
• declared: the service said so, and only the service;
• asserted: a caller claimed it on the way in (a value a browser sent, say), to be compared with what we witnessed;
• attested: an independent witness vouched for it (reserved, as above).

The grades are not a score. “Declared” is not a bad grade; it is an honest one. The card’s failure mode was never that a value was weak. It was that the card made a weak value look like a strong one.

The review that found the word already spent

Then we ran an adversarial review of the screens, looking for one thing: every place the card says more than its record.

It found two.

The first was the reserved word. “Attested” was already on screen, on a different panel, labelling a fingerprint of the result that nobody had signed. The fingerprint was real and useful. But a fingerprint you computed yourself is not a witness’s attestation, and calling it one spent the exact word we had just decided to keep in reserve. We had made the decision in a design discussion. The screen had been built earlier, separately, and nothing connected the two.

The second was an absolute. When a viewer was entitled to see everything, the card said “Nothing on this card is withheld.” An empty list cannot prove that. It can only say that nothing is listed as withheld. The sentence asserted a completeness the record never held.

Both were fixed the same day. The unsigned fingerprint now reads as exactly that: an unsigned fingerprint, with a separate label for the day it carries a signature. The absolute became “No withheld facts are listed for this view.” It is less reassuring and it is true.

Why the guard is a check

The lesson we took from the review is not “be careful with words”. We were being careful. We had written the rule down. The rule lost anyway, because a rule that lives in a design discussion is a memory, and memories do not run when someone else builds the next screen.

So the reserved word is now guarded by a test. It renders the card in every state it can be in, on every tab, and fails if the word “attested” appears anywhere. The day the independent witness exists, someone will have to change that test on purpose, in a reviewed commit, and the change will say why. Until then the word cannot leak back in by accident.

A reserved word is a reserved beat. Guard it with a check, not a memory.

The same shape works for every absolute a trust surface might be tempted to print: “all”, “none”, “every”, “verified”, “complete”. Each one is a promise about the whole record. If you cannot write the test that would catch the screen breaking that promise, the screen should not make it.

What we would tell a team building a trust card

1. Treat the copy as part of the claim. Headings, chips and colours get reviewed with the same question as the data: could the record back this?
2. Keep the wire honest and project down. Store the strongest true statement; let the display say less, never more.
3. Name who stands behind each value. A small fixed vocabulary beats a confidence colour. Readers can reason about “declared”; they cannot reason about amber.
4. Reserve the strong words. Decide which words you are not allowed to use yet, and why.
5. Turn every reservation into a test. A rule nobody runs is a wish.

This is the companion to Verified, Attested, Handed Off, which made the same argument about a sign-in debugging view: show what was observed, label what was reported, and show what is absent as absent. That post was about the values. This one is about the words around them. A trust surface can get every value right and still overclaim in its heading.