/freshness-contract

EXPERIMENTAL. A lookup, not a judgment ritual: it should cost LESS than the vibes it replaces. Fires only when prior evidence is about to be reused for a decision — never on every read, never as per-phase bookkeeping. It decides whether old proof still counts; what fresh proof must show belongs to your verification tools.

The design is deliberately isomorphic to HTTP caching (RFC 9111): explicit invalidation beats heuristics, conflicting signals resolve restrictively, and nothing is served stale silently. No TTL numbers ship in v1 — every "how old is too old" constant would be invented; the table routes by class and events, which are observable.

Step 1 — classify the artifact (volatility class)

Class is assigned per artifact kind at first encounter, not re-judged per use by whoever wants to skip a re-read.

Step 2 — check the observable signals

• Intervening writes — has the source (or its declared dependencies) changed since as_of? (fingerprint, mtime, generation stamp, commit)
• Named invalidators — did a declared invalidating event occur? (roster change, deploy, sync, schema bump, "re-prime after write")
• Decision leverage — is the reuse load-bearing for a decision, release, or Handler-facing claim, or merely orientation? Leverage is non-downgradable when the result supports a release, an irreversible or external action, a formal gate, or a Handler-facing recommendation — those are high, not judgment calls.
• Discriminator availability — does a cheap signal exist that is exclusive to the fresh state (a hash to recompute, a header to stat, a count to re-derive)?

Step 3 — the table (first match wins)

accept-labeled-risk is agent-electable ONLY on the no-cheap-discriminator row — it is never a bypass for a re-verify result elsewhere in the table. On any other row, proceeding despite a re-verify verdict requires explicit Handler authority (that is a Handler override, not a table output). Where it applies, it is never silent: the staleness risk is named next to the conclusion it feeds.

After the first matching policy is selected, handle discriminator availability for every spot-check result, including the default row: if no cheap exclusive discriminator exists, re-verify or explicitly accept labeled risk only where already permitted. Mandatory re-verification for invalidators, conflicts, high-leverage volatile evidence and load-bearing reports remains mandatory; this fallback never loosens those rows.

Output record (one line to a few lines, inline where the evidence is used)

freshness = { artifact, class, as_of, signals: {writes|invalidators|leverage},
              decision: reuse|spot-check|re-verify|accept-labeled-risk,
              discriminator_used?: <what was checked> }

No dedicated log stream, no cards, no sink — the record rides inside whatever report or decision consumed the evidence.

Safety boundary

• Signals are observable properties of sources and events — never the agent's feeling of confidence about its memory.
• The table may be narrowed by a Handler's local policy (stricter rows); agents never loosen a row.
• TTLs, if ever added, must come from logged staleness observations, not authorship-day guesses; until then age alone never justifies reuse or refusal.
• Foreign freshness metadata (another party's "this is current" claim) is a report, not a signal — classify accordingly.

Self-improvement. On completion, run the Self-Improvement Protocol (self-improve/SKILL.md): apply its signal taxonomy and threshold to this run; surface any surviving proposal for handler approval. Conservative — silent otherwise. Never auto-apply.