Crate rto_graph 

Provenance-tagged knowledge graph store.

Every edge in a Roteiro graph carries a Provenance tag recording how it was produced: deterministically derived from source ASTs, authored by a human or agent in an ADR/blueprint, or inferred heuristically from docs and other artifacts. See ADR-0001.

The graph is a set of Nodes addressed by a deterministic natural Node::key, connected by Edges. Facts extracted from one source blob are grouped into a FactSet and applied atomically to a Store.

@rto:0001

Structs

BlobRef

A blob in a tree: its repository-relative path and hex object id.

ContextRefresh

Counts from a refresh_contexts pass.

DebtItem

One intent-debt finding in a DebtReport.

DebtReport

The intent-debt inventory: every marker node, grouped and listed. A deterministic, provenance-derived view of what is incomplete or deferred.

Edge

An edge in the knowledge graph, connecting two nodes by their keys.

EdgeRef

One end of an edge as seen from a subject node: the relationship, how it was produced, and the node on the other end.

Explanation

A node together with its provenance-labelled neighbourhood.

FactSet

The set of nodes and edges extracted from a single source blob (or otherwise assembled together). Applying a fact set to a crate::Store is atomic.

FileNodeExtractor

Fallback extractor: emits a single file node per blob, tagged with its blob hash and basic size metadata. Produces no edges. Used for files with no registered language.

GraphArtifact

A self-describing snapshot of an assembled graph.

ImportApplied

A summary of applying/re-applying import layers (see Store::apply_import_layer and Store::reapply_imports).

IngestConfig

Runtime ingestion toggles (ADR-0007 [ingest]): which blob content is extracted for embedding. Every toggle defaults to on, and a toggle only gates content within a build that supports it — turning pdf on cannot extract PDF text in a binary built without the pdf-text feature, but turning it off suppresses that content in a binary that has it.

Listing

A listing of all nodes of one kind.

Node

A node in the knowledge graph.

NodeContext

A node together with its one-hop neighbourhood and a validity fingerprint.

NodeSummary

A compact node summary (used in listings and as the subject of an Explanation).

ObjectCache

A content-addressed store of fact sets on disk.

OracleReport

The result of comparing Roteiro’s derived graph against a codegraph snapshot. Counts cover Rust function/struct/enum/trait symbols (the overlap where both tools operate) and function-to-function calls.

Path

A shortest path between two nodes. Edges are followed in either direction (the graph is treated as undirected for reachability), and each hop records the actual direction and provenance of the edge used.

PathHop

One step along a Path: the edge traversed and the node it leads to.

Registry

Dispatches extraction to a language-aware extractor by file extension, falling back to a plain file node when no language is registered. After the language extractor runs, [crate::markers] appends any intent-debt markers (TODOs, stubs, deferred-work notes) found in the blob. Carries the runtime IngestConfig applied to content extraction.

Repo

A discovered git repository.

RustExtractor

Derived extractor for Rust source, backed by tree-sitter. Emits a file node, one symbol node per fn/struct/enum/trait/mod (and a few others) with defines/contains edges reflecting lexical nesting, and imports edges for use declarations. Each function records the simple names it calls in meta.calls for later cross-file resolution.

SearchHit

A relevance-ranked search hit: a node summary plus its score.

Span

A byte-offset range within a source blob (start..end).

Store

A Roteiro graph store backed by a single SQLite database.

SyncReport

A summary of the work a sync performed.

Enums

CacheError

Errors raised by the object cache.

Direction

Direction of traversal when querying a node’s neighbours.

EdgeKind

The kind of a graph edge (the relationship it records).

GitError

Errors raised while reading from a git repository.

NodeKind

The kind of a graph node.

OracleError

Errors raised while comparing against a codegraph snapshot.

Provenance

How an edge in the graph was produced.

StoreError

Errors raised by the store.

SyncError

Errors raised while syncing.

Constants

ARTIFACT_SCHEMA

Versioned schema tag for the artifact envelope. Bump on any breaking change.

ORACLE_SCHEMA

Stable schema tag for the oracle report.

SCHEMA

The versioned schema tag emitted on every query result. Bump the version on any breaking change to the shape.

Traits

Extractor

Turns one source blob into the nodes and edges derived from it.

Functions

build_context

Build a node’s context bundle from the current graph (ignoring the cache). Returns None if no node has that key.

compare_codegraph

Compare Roteiro’s derived graph (store) against a codegraph snapshot at db_path, returning an OracleReport. Read-only on both sides.

context

Fetch a node’s context through the cache: return the cached bundle when its fingerprint still matches the current graph, otherwise rebuild it, store it, and return the fresh bundle. Returns None (and prunes any stale entry) if the node no longer exists.

debt

Inventory intent-debt markers in the graph, optionally restricted to the given categories (empty means all). Ordered by (path, line) so output is stable and reads top-to-bottom per file.

dependents

The set of nodes whose cached context a change to any of changed would invalidate: the changed nodes themselves plus their one-hop neighbours in either direction (a node’s context reaches exactly one hop out). This makes the dependency-propagation contract explicit; refresh_contexts realises it via fingerprints.

explain

Explain a node: its record plus every incoming and outgoing edge, each labelled with provenance. Returns None if no node has that key.

list_kind

List every node of the given kind, ordered by key.

path

Find a shortest path from from to to, following edges in either direction. Returns a Path with found = false (and no hops) if either endpoint is absent or to is unreachable; from == to yields the trivial zero-length path.

refresh_contexts

Refresh every cached context that has gone stale (its node or a neighbour changed) and prune entries whose node no longer exists. Only existing nodes that already have a cache entry are considered — this reconciles the cache with the current graph without eagerly materialising context for every node.

search

Deterministically search node names/keys/paths for query, ranked by relevance, returning at most limit hits. Case-insensitive; every whitespace/::-separated token in query must appear somewhere in the node. Scoring favours an exact name match, then a name substring, then per-token hits across name/key/path. Ties break by key so results are stable.

sync

Sync store to the repository’s HEAD tree, extracting changed blobs with extractor and caching results in cache.

sync_worktree

Sync store to the working tree: the committed HEAD state with uncommitted edits to tracked files overlaid on top (a pre-commit preview).