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.

ChangedFile

A file that differs between the working tree (or a base revision) and HEAD.

ConfigKey

A single leaf config setting: its dotted key, source file, and value.

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 postponed.

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 (intent-debt markers) found in the blob. Carries the runtime IngestConfig applied to content extraction.

Repo

A discovered git repository.

ResolvedWorkspace

A workspace group after config normalisation (crate::WorkspaceSet input): a name, its member roots/repos (unexpanded — discovered when the set is built), and whether its repos are cross-linked (served as one multi-repo graph) or standalone (each its own single-repo graph, no cross-repo links).

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 (optionally scope-qualified) names it calls in meta.calls for later cross-file resolution — see [RustWalk::callee_name].

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.

Submodule

A git submodule pinned in a tree: its repo-relative path, the commit it points at (the gitlink oid — the version pin a deployment ships), and its configured URL from .gitmodules when registered there.

SyncReport

A summary of the work a sync performed.

Workspace

A named set of per-repo graphs, each opened on demand and cached. Cheap to hold: the stores are small SQLite files opened lazily; the caller (a server) holds the one expensive model. The registry is reloadable in place.

WorkspaceSet

An install’s many named workspaces: linked groups (multi-repo graphs) and standalone singletons (one-repo graphs), keyed by name in stable order (ADR-0008 multi-workspace). The outer layer over Workspace: it selects which workspace a command operates on, then hands back that Workspace to resolve projects within it. Built from normalised config (WorkspaceSet::from_resolved) so the serve/links selection logic is shared.

Enums

CacheError

Errors raised by the object cache.

ChangeStatus

How a file changed relative to the comparison baseline — for review labelling.

Direction

Direction of traversal when querying a node’s neighbours.

EdgeKind

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

Follow

The outcome of Workspace::follow_definition: where a cross-repo follow-hop lands.

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 or node in the graph was produced.

StoreError

Errors raised by the store.

SyncError

Errors raised while syncing.

WorkspaceError

A failure resolving or opening a project’s graph.

Constants

ARTIFACT_SCHEMA

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

EXTERNAL_REF_KIND

The node-kind token for an external-ref placeholder — a stand-in, in one repo’s store, for a node that actually lives in another repo’s graph.

LINKS_REF

The import-layer src_ref under which inferred cross-repo links are persisted (see crate::Store::apply_import_layer). Its own producer, so re-inferring can re-derive it authoritatively without touching other import layers.

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) and excluding markers whose file path matches any ignore glob (config [debt] ignore — empty means keep all). Ordered by (path, line) so output is stable and reads top-to-bottom per file; total and by_category reflect the retained markers only.

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.

discover_repos_under

Shallow git-repo discovery under root: the root itself if it is a repo, plus each immediate subdirectory that is one, in sorted order. Shallow by design — a code directory holding sibling checkouts is the common case, and a deep scan would be slow and surprising. Shared by the CLI’s workspace collection and WorkspaceSet / config resolution, so the membership rule lives in one place.

explain

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

external_ref_key

The store key of the external-ref node for qualified — the qualified target under an extref: namespace, so it never collides with a real node key.

external_ref_node

Build an external-ref placeholder node for a project-qualified target key (<project>::<key>, ADR-0009). The node lives in the referring repo’s store so an inferred edge to the (foreign) target satisfies store integrity; its qualified target is recorded in meta so crate::Workspace::follow_external_ref can resolve it across the workspace. Tagged Provenance::Inferred.

external_ref_target

The project-qualified target of an external-ref node, or None if node is not one. Read from meta.qualified, falling back to the extref: key prefix so a node written by an older layer still resolves.

flatten_config

Flatten a config file’s bytes into leaf keys, dispatched by extension. An unparseable file yields nothing (a config we can’t read is not an error here).

is_config_path

Whether a repo-relative path is a config file this module understands: *.toml, *.json, *.yaml, *.yml, *.env, or a dotenv name (.env, .env.<x>).

is_secret_key

Whether a config key’s name looks like it holds a secret (token, password, credential, …). Extraction redacts the value of such keys so secrets from .env/config files are never persisted into the graph store (which is queryable and exportable). Matched against the key with separators removed, so API_KEY, apiKey, and api-key all count.

list_kind

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

normalize_config_key

Normalise a dotted key for matching: lowercase, split on any non-alphanumeric run, join with .. So SERVE_ADDR, serve.addr, and serve-addr all become serve.addr and match across TOML / env / JSON conventions.

parse_qualified

Split a project-qualified key "<project>::<key>" into (project, key), or None if it carries no :: separator (a bare, within-repo key). A project name never contains ::; a bare key may itself contain single colons (e.g. sym:rust:…), so only the first double-colon separates the project (ADR-0009).

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 nodes for query, ranked by relevance, returning at most limit hits. Case-insensitive; every whitespace/::-separated token must appear somewhere in the node’s name, key, path, or captured meta.content (so a question’s words find the description, e.g. a README/ADR, not only a same-named symbol). Scoring favours an exact name match, then a name/content substring, then per-token hits; it then boosts curated intent (authored ADRs/blueprints) and READMEs/overviews and penalises test scaffolding, so “what/why” questions land on the real answer rather than a same-named test helper. 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_index

Sync store to the git index — the staged tree that a commit would record. Unlike sync_worktree (files on disk) this reads each staged blob by its index object id, so it validates exactly what is about to be committed (partially-staged changes and all). New staged files are included; unstaged working-tree edits are not. Backs the index-aware pre-commit gate.

sync_tree

Extract a repo’s derived graph at an arbitrary commit/tree rev into store, replacing its contents — the same content-addressed extraction as sync, but for a historical point rather than HEAD. Because extraction is keyed by (path, blob oid, env), every blob unchanged versus another synced point is a cache hit, so resolving an older version only re-does what differs.

sync_worktree

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