mixle.substrate.trust module

verify_lineage() – check that an item’s provenance chain is intact (trust / provenance, N1).

Every substrate item can point at the items it derives from – links are KG/lineage edges (parent documents, the model that produced an artifact, the trace it came from). A citation or a merge is only trustworthy if that chain actually resolves: a link to an item that no longer exists is a dangling provenance edge, and any claim resting on it is unverifiable. verify_lineage() walks an item’s ancestry, reporting which links resolve and which dangle, and how deep the intact chain goes. audit_substrate() runs it over the whole store – a knowledge-integrity sweep, the same “trust is re-derivable, not asserted” discipline the factuality receipts apply to answers, applied here to the knowledge itself.

class LineageReport(item_id, intact, n_links, dangling=<factory>, depth=0, visited=0)[source]

Bases: object

Whether an item’s provenance chain resolves end to end – and where it breaks if it doesn’t.

Parameters:
item_id: str
intact: bool
n_links: int
dangling: list[str]
depth: int = 0
visited: int = 0
as_dict()[source]
Return type:

dict[str, Any]

verify_lineage(substrate, item_id, *, max_depth=20)[source]

Walk item_id’s ancestry via links, reporting dangling edges and intact depth (cycle-safe).

An item is intact iff every lineage link, transitively, resolves to an item that exists. Cycles are handled (each id is visited once). max_depth bounds pathological chains. A missing root item yields intact=False with itself recorded as dangling.

Parameters:

  • substrate (Substrate)

  • item_id (str)

  • max_depth (int)

Return type:

LineageReport

audit_substrate(substrate, *, scope=None)[source]

A knowledge-integrity sweep: how many items have intact lineage, and every broken one named.

Returns {n_items, n_intact, n_broken, broken: [{item_id, dangling}, ...]} – the store’s trust surface at a glance, so a broken provenance edge surfaces as a finding rather than a silent lie.

Parameters:

  • substrate (Substrate)

  • scope (str | None)

Return type:

dict[str, Any]