Cache the Facts, Not the Verdict

#resources #resources/programming #resources/programming/architecture

Cache the facts, not the verdict

A local mirror can answer factual reads at speed. It should not issue judgments. Derived verdicts — the scores and decisions that carry authority — belong to the source, not to whatever you recomputed from a cache that might be stale or missing context.

Two truths, on purpose

The lcos CLI runs on two truths at once. Convex is the cloud source of truth and the only place a coaching verdict is produced. Local SQLite is a fast, disposable mirror of the facts.

That split shows up directly in how the CLI answers questions:

lcos ask "how's my HRV trending" is Tier-1. It computes a rolling average and a period-over-period delta from the local mirror. Deterministic, offline, no model in the loop. It reports a fact.
lcos ask --deep "should I deload this week" is Tier-2. It proxies the verified coach on Convex and waits for a real answer. It returns a judgment.

The CLI will tell you your HRV is down 6ms. It will not, on its own, tell you to deload. That's a verdict, and a verdict comes from the authority.

Why the line matters

If the mirror computed a readiness verdict locally and it disagreed with the source, the user gets two different answers from one product, and the more confident-sounding one wins. The local copy is also the one most likely to be wrong about a judgment: it can be a sync behind, or missing the dedup and source-priority logic the source applies before it decides anything.

This is the inverse of Stale Registries Need Local Authority. There, the local process owns a live resource and its state is evidence a remote registry lacks. Here, the source owns the judgment and the local mirror must not quietly usurp it. Same question from opposite sides: who actually holds the authority here?

The test

Ask of any cached read: am I reporting a fact or making a judgment? Facts can live in the cache. Judgments stay with the authority, even when that costs a round-trip.

Validation against code (2026-06-26)

Tier-1 reads run as deterministic store aggregations in apps/cli/crates/daemon — no model, no verdict.
lcos ask --deep posts to /api/ios/coach/start and polls /run; the verdict is whatever the verified coach returns.
apps/cli/docs/contract.md states the rule outright: verdicts only from Tier-2.

Why this generalises

Any read replica, edge cache, or offline mirror of a system that also makes decisions hits this: pricing, risk scoring, recommendations, content moderation. Serve the facts locally for speed; route the decision to the authority. Don't let a cache start ruling.