Set freshness budgets

A freshness budget is how long a value stays fresh after its source last confirmed it. When the budget runs out, Census still returns the value and marks it stale. Consumers decide what to do with stale values: Census reports freshness and does not enforce it.

[inventories.devices.freshness]
default = "1h"           # every field and the location
status = "30s"           # the status field

Key	Meaning
default	The budget of every field without its own budget, and of the location. One hour when it is not set.
A field name	The budget of that field.

Durations are a number followed by s, m, h or d. Census refuses to start when a key is neither default nor a declared field.

When a source confirms a value

A full refresh confirms every value it observes, including values that did not change. A webhook confirms the values of the object it fetched. A failed refresh confirms nothing, so values from a source that is down become stale once their budget runs out.

A budget shorter than the contribution's refresh_interval makes values stale between two refreshes. With refresh_interval = "5m" and a budget of 30s, a status value that no webhook confirms is stale for 4 minutes 30 seconds of each interval.

What consumers read

• Each entity has a freshness block: stale if any of its non-null resolved values is stale, otherwise fresh, and the oldest confirmation time among those values.
• Full detail gives each observation's confirmed_at and freshness.

Freshness and completeness are separate. A stale value does not make the inventory incomplete, and a source that is down keeps its priority.