Module query 

BFS reachability search and orphan/stub detection.

Structs

Connectivity

One entity’s degree counts. total == incoming + outgoing; kept explicit so the JSON wire shape is self-describing and callers don’t re-derive it.

ReachedVia

One entity reached by reachable_via: the edge label it was first reached by, the depth of that first reach (1 = direct neighbour), and the direction that reaching edge was traversed in — so a both walk stays interpretable per hit.

Enums

TraversalDirection

Traversal direction relative to the seed, applied at EVERY hop — depth > 1 is a pure transitive closure in the chosen direction, never a mixed walk (an entity reachable only by alternating directions is not in an out or in result at any depth; that per-hop property is what makes a fall-through analysis correct).

Functions

cmp_by_dependency

Centrality ordering: dependency degree (typed_total) descending first, then raw total descending, then id lexicographic ascending as a stable deterministic tie-break. Ranking by typed_total keeps a co-mention-inflated hub from outranking a real dependency hub.

connectivity_for

Compute one entity’s raw and typed degree. incoming_counts decides which incoming edges contribute (e.g. source-in-mem scoping for a mem-filtered health view); every outgoing edge always counts. Typed degree excludes EdgeSource::BodyLink (auto-emitted mention) edges.

find_orphans

Find orphan entities — non-stub entities with no edges at all (completely isolated).

find_orphans_with_schemas

Schema-aware orphan scan: like find_orphans, but entities whose type declares leaf: true in their mem’s schema are exempt — a leaf is edge-less BY CONSTRUCTION, so counting it as an orphan is noise that masks real orphans (agent-trust plan 06). The exempted population stays visible through leaf_population. An empty schema map (tests, ad-hoc callers) reproduces the schema-blind behaviour exactly.

find_stubs

Find stub entities — entities created from unresolved references. Returns each stub with the list of entities that reference it.

leaf_population

The leaf population health reports beside the orphan axis: for every leaf-declared type with at least one real entity, the count of its entities, keyed <schema_ref>:<type>. Visible, never vanished — the reader still sees the population the orphan exemption covers.

most_connected

Find the most connected non-stub entities, ranked by dependency degree (typed edges) — see cmp_by_dependency. Returns up to limit entries.

reachable_distances

Returns each reached entity’s hop-distance from from — the depth at which BFS first reaches it (from itself is 0), following only edges admitted by direction at every hop. The distances drive proximity ranking of a related_to neighbourhood: nearer first.

reachable_via

Find all entities reachable from from by walking only edges whose rel_type is in edge_types, up to max_depth hops, following only edges admitted by direction at every hop. Returns one ReachedVia per reached entity — never from itself.

would_cycle

Would adding an edge from --rel_type--> to close a cycle in the subgraph restricted to edges of rel_type? Returns the back-path as [to, …, from] when a cycle exists, None otherwise.