Oracles

Most sources earn their reputation over time. An oracle skips that process: Veritas treats it as maximum trust in every scope and never adjusts its reputation. Oracles are for sources that are definitionally right — a CI gate, a human adjudicator, a settled ground-truth record — not for agents that are merely usually right.

The Oracle shape

Installing Veritas adds an Oracle thing shape — the fifth Veritas shape. An oracle source is a thing of that shape, and all its fields are optional:

Field	Type	Purpose
displayName	string (optional)	Human-readable name for the oracle.
description	string (optional)	What ground-truth authority this oracle represents.
owner	wref (optional)	Who is responsible for the oracle in this repo.

An Oracle thing carries no opinion fields. It is not an opinion — it is the source that an opinion names.

Creating and using an oracle

Create the oracle thing, then name it as the source on any Certainty, Support, or Opposition:

# 1. Create the oracle source thing
wh thing create Oracle/ci-gate \
  --data '{
    "displayName": "CI gate",
    "description": "Authoritative pass/fail from the release pipeline.",
    "owner": "Person/release-eng"
  }' \
  --repo [your-org]/[your-repo]

# 2. Write an opinion sourced from the oracle
wh assertion create --shape Certainty \
  --about Proposition/build-1234-passed \
  --data '{"belief":1,"disbelief":0,"uncertainty":0,"source":"Oracle/ci-gate"}' \
  --repo [your-org]/[your-repo]

Veritas recognizes an oracle by the Oracle/ prefix on the source wref — any source whose shape segment is Oracle is treated as an oracle. There is no separate registration step.

How oracles behave

• Fixed maximum-trust reputation. An oracle’s reputation is pinned at the maximum in every scope — full belief, capped just short of total certainty (the same cap any seeded reputation hits; see Reputation). No amount of evidence raises or lowers it.
• Never adjusted. An oracle’s reputation is frozen. It does not move under disagreement, and Veritas ignores any reputation row stored for an oracle wref — including one written with upsert-reputation, which is accepted but has no effect.
• Almost undiscounted, never wagering. Because its reputation is maximum trust, an oracle’s opinion passes through almost undiscounted. And because the reputation never moves, an oracle never wagers anything — it cannot lose standing by disagreeing with other sources.
• Conflicting oracles are not resolved. If two oracles disagree on the same target, both stay at maximum trust and the Consensus reflects the conflict — Veritas has no rule for adjudicating between two definitionally-true sources. Keep one oracle per question domain.

When to use an oracle

A single trusted ground-truth source is the fastest way to bootstrap a fresh install: it immediately gives Veritas an anchor to calibrate other sources against. Use oracles deliberately:

• Only for definitionally-true sources. CI results, human adjudicators, authoritative records — sources that define the answer. An agent that is usually right is a high-reputation source, not an oracle: seed it (see Reputation) and let its reputation recalibrate.
• Put error bars in the opinion, not the reputation. If a ground-truth source is occasionally wrong, express that doubt in each Certainty’s uncertainty mass — not by lowering the oracle’s reputation, which you cannot do anyway.
• One oracle per question domain. Because conflicts between oracles are not resolved, do not point two oracles at the same kind of question.
• Assign an owner. An oracle’s reputation cannot be corrected after the fact, so a wrong oracle opinion can only be fixed by revising the assertion itself. Name an owner who can do that.

Related

• Reputation and the CLI — how ordinary reputation is tracked, read, and seeded.
• Writing opinions — author Certainty, Support, and Opposition.
• Install Veritas — the five shapes and what install creates.