Core concepts

Faro is a verification engine. You hand it an artifact — a URL, a payee, or a message — and it hands back one verdict object. Everything below describes the parts of that object and how it is produced.

The verdict

Every response is the same VerdictResult shape, whatever the artifact type:

Field	Meaning
`verdict`	🟢 `green`, 🟡 `yellow`, or 🔴 `red` — the traffic-light answer.
`confidence`	`0.0`–`1.0`. How sure Faro is.
`reason`	One plain-language line. Always present — it is the product.
`recommended_action`	`allow` / `warn` / `block` / `review` — branch your code on this.
`signals`	The evidence behind the verdict (see below).
`explanation`	Optional longer-form context.
`cached`, `first_seen`, `checked_at`	Freshness metadata.

Verdicts

🟢 Green — allow

No safety problems found. Safe to proceed.

🟡 Yellow — warn / review

Something is uncertain or mildly concerning. Slow down; ask the user.

🔴 Red — block

A confirmed or strong threat. Do not proceed.

Signals

A signal is a single piece of evidence with a severity (info → low → medium → high → critical), a human-readable detail, and its source (e.g. safe_browsing, rdap, opensanctions, payee_format, llm). The verdict is a deterministic function of the signals — strong evidence raises the verdict, and a confirmed-bad signal forces red regardless of anything else.

The tiers

Faro decides cheaply first and only reaches for the model when it has to:

Tier 1 — deterministic checks
Fast, high-precision checks decide the clear cases: Google Safe Browsing and domain age (RDAP) for URLs; sanctions screening and payment-handle format detection (UPI, Venmo, Cash App, Pix, IBAN, and more) for payees; link extraction for messages.
Tier 2 — prior signals
Anything Faro has already recorded about this artifact, folded into the verdict.
Tier 3 — LLM reasoning (only if needed)
When the deterministic tiers are inconclusive, an LLM reasons about brand impersonation, mule patterns, and scam tactics. It never overrides a confirmed-bad deterministic signal.

Caching & freshness

Repeat artifacts are cached with verdict-aware TTLs: a confirmed 🔴 is cached long, a 🟢 is cached briefly (a clean domain can be weaponized any time), and 🟡 / low-confidence results are barely cached at all. Responses carry X-Faro-Cache: hit|miss and a cached flag so you feel the speed without ever being served a stale "safe."