Substrate honesty
The artifact tells the truth about its own state.
Every value the platform shows you carries — explicitly or implicitly — a claim about how it came to be true. Live, cached, snapshot, synced, computed: these are different facts. A trust score computed from 30 days of events is not the same kind of value as one snapshot at month-end. The surface must say which.
Where you'll see it: the <Provenance> pill on values across the storefront and admin. Anywhere a number could mislead by not naming its origin, the pill names it.
Where this lives in code. The canonical principle isdocs/principles/substrate-honesty.mdin the repo. The companion audit (pnpm audit:honesty) measures compliance. The UI primitive is<Provenance>inapps/admin/src/lib/ui/and the corresponding storefront primitive library.
The four-question checklist
Before shipping a new value or score, the platform asks four questions:
- How was this value produced? (live? cached? computed?)
- What does it claim to be true of? (the user? the listing? the market?)
- When was it last refreshed? (and what does staleness mean for it?)
- Who can see it? (the subject? an operator? an external auditor?)
If any of these can't be answered, the value is not yet ready to ship.
Why this exists
A platform that hides the provenance of its values is a platform that asks you to trust the surface without showing you the substrate. The opposite — naming the substrate explicitly — gives you the standing to verify, contest, or trust as you choose. It is the first of the four doctrines and the precondition for the rest.