mixle.substrate.freshness module

Freshness checks for substrate knowledge items.

Models drift; so does knowledge. An item can go stale three ways, each independently checkable:

  • moved data – the item references a file (payload.ref / provenance.source/path) that no longer exists, or whose content hash no longer matches the one recorded at ingest;

  • superseded – a newer item shares the same lineage parent or declares supersedes on this one, so this item is no longer the current version of its knowledge;

  • aged out – older than the caller’s max_age_s policy for its kind (a soft signal: age alone is a review trigger, not proof of wrongness – the finding says so).

check_freshness() audits one item and names every signal; freshness_report() sweeps a store. These checks help monitoring workflows surface stale citations and moved artifacts before they affect downstream answers.

class Freshness(item_id, fresh, signals=<factory>, age_s=0.0)[source]

Bases: object

One item’s freshness verdict: fresh iff no staleness signal fired; every signal named.

Parameters:
item_id: str
fresh: bool
signals: list[str]
age_s: float = 0.0
as_dict()[source]
Return type:

dict[str, Any]

content_hash(path)[source]

The sha256 (first 32 hex) of a file’s bytes, or None if unreadable – record this at ingest.

Parameters:

path (str)

Return type:

str | None

check_freshness(substrate, item_id, *, max_age_s=None, now=None)[source]

Audit one item for the three staleness signals (see module docstring). Missing item -> stale.

Parameters:

  • substrate (Substrate)

  • item_id (str)

  • max_age_s (float | None)

  • now (float | None)

Return type:

Freshness

freshness_report(substrate, *, max_age_s=None, scope=None, now=None)[source]

Sweep a store for stale knowledge: {n_items, n_fresh, n_stale, stale: [...]} – the monitor feed.

Parameters:

  • substrate (Substrate)

  • max_age_s (float | None)

  • scope (str | None)

  • now (float | None)

Return type:

dict[str, Any]