Skip to content

Verification metadata for civic facts: attribution, freshness, and staleness budgets #299

Description

@ThatXliner

Why

Every civic fact the How to Vote screen shows needs to answer three questions:
who said this, where does it come from, and when did we last check? The
design makes "Last verified {date}" a required element — when the timestamp is
missing it renders "Verification date unavailable" rather than dropping the
row.

Nothing in the codebase can supply that today. civic_api_cache stores
fetched_at, but that is when Billion called an API, not when the
authority published or when a human verified the value.

This is the shared substrate under #294#297. Without it, each of those ships
its own ad-hoc provenance and they drift.

What to build

A provenance record attachable to any civic fact:

  • value
  • sourceName — the authority, verbatim
  • sourceUrl
  • fetchedAt — when we retrieved it
  • verifiedAt / verifiedBy — when a human last confirmed it, if ever
  • staleAfter — per-field freshness budget

Proposed budgets, needs a decision: locations 24h (matches the existing
voterinfo cache TTL), deadlines 7 days, ID rules 30 days. Past the budget the
field shows its age rather than disappearing.

Related prior art

MeasureCitationRef in packages/api/src/lib/civic.ts already does per-field
attribution with a trust tier for ballot measures. That model is the obvious
starting point — this issue generalizes it beyond measures.

Done when

  • A shared provenance type used by every voting-logistics field
  • Field-level rather than record-level, so partial verification is
    representable ("locations verified, deadlines unavailable")
  • Staleness budgets agreed and enforced
  • The UI can render "Verification date unavailable" from a real absence

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions