Crate rto_graph

Expand description

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

Re-exports§

pub use media::CandidateCount;
pub use media::GateReason;
pub use media::GateThresholds;
pub use media::GeneratedContent;
pub use media::MAX_MODEL_ID;
pub use media::MAX_PROMPT;
pub use media::MEDIA_PRODUCER_PREFIX;
pub use media::MEDIA_SCHEMA;
pub use media::MediaBlob;
pub use media::MediaBuildOptions;
pub use media::MediaBuildReport;
pub use media::MediaError;
pub use media::MediaFilter;
pub use media::MediaKind;
pub use media::MediaOutcome;
pub use media::MediaProducer;
pub use media::MediaRecord;
pub use media::MediaSkip;
pub use media::MediaStatus;
pub use media::MediaWrite;
pub use media::Producer;
pub use media::ProducerId;
pub use media::ProducerSummary;
pub use media::ProducerSummaryAvailable;
pub use media::SkipEntry;
pub use media::build_media;
pub use media::is_valid_model_id;
pub use media::media_blobs;
pub use media::status as media_status;
pub use trust::ProducerTrust;

Modules§

compile_claim: When a green check refutes “this will not compile” — and when it does not (Stage 35).
media: Generated media content — a separate artifact store, never a graph fact.
review_corpus: The adjudicated review corpus, as a type (Stage 35).
review_score: Scoring a candidate reviewer against the adjudicated corpus (Stage 35).
reviewer: The reviewer’s pure core: what to ask, how to read the answer, and what the answer is allowed to claim (Stage 35b).
trust: How much a producer’s identity can be trusted — ADR-0019 §5.

Structs§

AdvisoryDb: The pinned advisory database a run consulted, and when it was published.
AnalysisRun: One analyzer execution, plus everything needed to reproduce or distrust it.
BlobRef: A blob in a tree: its repository-relative path and hex object id.
BoundedEdges: One direction of a bounded bundle: the edges kept, and an exact account of what was dropped to fit.
CacheEntry: One entry in the cache tier, with its anchor resolved against the current graph.
CacheStats: What the cache tier currently holds, against what it is allowed to hold.
CacheSweep: What one sweep of the cache tier did.
CacheWrite: The values crate::Store::agent_cache_put writes.
ChangedFile: A file that differs between the working tree (or a base revision) and HEAD.
CommandPolicy: The command policy a run was executed under. Part of the evidence chain: it records what the run was allowed to do, not merely what it did.
ConfigKey: A single leaf config setting: its dotted key, source file, and value.
ConfigSecretItem: One secret-named config key in a ConfigSecretReport.
ConfigSecretReport: An inventory of secret-named config keys and their redaction state.
ContextEdge: One incident edge as seen from the subject: the relationship, its provenance, and the node on the other end. Owned/round-trippable for caching.
ContextNode: A compact node summary within a NodeContext. Owned and round-trippable so the whole bundle can be cached as JSON and read back.
ContextRefresh: Counts from a refresh_contexts pass.
CouplingItem: One node’s directed call coupling in a CouplingReport.
CouplingReport: Directed call coupling: per-node fan-in and fan-out over Calls edges, ranked. The counterpart to an undirected degree ranking, which cannot tell “everything calls this” from “this calls everything”.
DebtDensityReport: Intent-debt density: markers per file normalised by file length, ranked. The counterpart to debt, which reports markers and therefore ranks large files first by construction.
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.
DensityItem: One file’s intent-debt density in a DebtDensityReport.
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.
Finding: One finding, belonging to an AnalysisRun.
FindingKey: A finding’s stable identity across runs.
FindingsApplied: A summary of replacing a findings layer (see crate::Store::replace_findings_layer).
FindingsLayer: A live layer: its run and the findings that run owns, ordered by key.
GeneratedHit: A hit in the generated channel: text a model produced about a media blob, never a graph fact.
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]). 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.
MediaEngineGuard: Ties the lifetime of the process-wide media engines — and, after them, the llama.cpp backend they share — to a scope: dropping the guard runs release_media_engines.
MemoryAnchor: Where a record is anchored, as captured when it was written.
MemoryFilter: A narrowing filter for crate::Store::memory_records.
MemoryForgotten: What one crate::Store::forget_memory removed.
MemoryHit: A hit in the memory channel: something a session learned, never a graph fact and never a re-derivable one.
MemoryListing: A listing of memory records, with the counts that make it legible.
MemoryRecord: One stored memory record.
MemoryWrite: The values crate::Store::record_memory writes.
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.
ObjectSweep: What one ObjectCache::sweep pass did.
OmittedEdges: How many edges of one kind were left out of a truncated direction.
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.
Recall: A ranked recall, with the state it was computed against.
RecallOptions: How to recall.
Recalled: One recalled record and the arithmetic that ranked it.
ReclaimReport: What one sweep_superseded pass did — and, for everything it kept, why.
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].
SchemaAhead: A store written by a build newer than this one: it records migrations this binary has never heard of. Produced by Store::schema_ahead.
SearchHit: A relevance-ranked search hit: a node summary plus its score.
SearchOptions: How to search.
SearchResults: The three channels a search returns.
SourceIdentity: The source identity a run was executed against.
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.
ToolContext: A node’s context bundle, bounded for a model-facing tool surface.
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.
WorktreeId: An identifier for one checkout, used as the last component of a layer key.

Enums§

AnchorState: What a record’s anchor is worth right now, computed on every read against the current graph and never stored.
CacheError: Errors raised by the object cache.
ChangeStatus: How a file changed relative to the comparison baseline — for review labelling.
CouplingOrder: How a CouplingReport’s items are ranked. The three orders answer three different questions, which a single undirected degree cannot tell apart.
Decay: How a record’s age is priced into its recall score.
DensityOrder: How a DebtDensityReport’s files are ranked.
Direction: Direction of traversal when querying a node’s neighbours.
EdgeKind: The kind of a graph edge (the relationship it records).
EnvironmentPolicy: How the analyzer’s process environment was prepared.
FindingsError: Errors raised when constructing the identity values this store is keyed by.
Follow: The outcome of Workspace::follow_definition: where a cross-repo follow-hop lands.
GitError: Errors raised while reading from a git repository.
GraphSource: Which tree the graph — derived layer and authored layer — is built from: the committed HEAD, the working tree (uncommitted edits on disk), or the git index (the staged tree a commit would record).
Isolation: The isolation boundary a run actually had — recorded honestly, so a result produced with no boundary can never read as if it had one.
MemoryError: Errors raised when writing or forgetting a memory record.
MemoryKind: What kind of knowledge a record holds.
NetworkPolicy: What network access a run was permitted.
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.
RedactionState: The redaction state of one config key in a ConfigSecretReport. Three states, because collapsing them would misreport two of them: “declared in code” is not a redaction, and “value present” is not a safe one.
RunnerKind: Which backend produced an AnalysisRun.
Severity: The severity an analyzer assigned to a finding.
StoreError: Errors raised by the store.
SyncError: Errors raised while syncing.
WorkspaceError: A failure resolving or opening a project’s graph.
WorktreeAccess: How the analyzed worktree was exposed to the analyzer.

Constants§

ARTIFACT_SCHEMA: Versioned schema tag for the artifact envelope. Bump on any breaking change.
CACHE_BUDGET_ENV: Environment variable that raises or lowers DEFAULT_CACHE_BUDGET_BYTES, in whole megabytes — so a large repository can hold more without a rebuild.
CACHE_SCHEMA: Stable schema tag on CacheSweep and CacheStats.
DEFAULT_BASE_CONFIDENCE: The base_confidence used for a record whose writer offered none — the midpoint of the range a writer can state.
DEFAULT_CACHE_BUDGET_BYTES: The default byte budget for the cache tier: 256 MB, and raisable.
DEFAULT_DECAY_SPAN: Default span for Decay::Linear, in generations — one generation per record written, never a second of wall-clock.
DEFAULT_HALF_LIFE: Default half-life for Decay::Exponential, in generations.
DEFAULT_KEEP_GENERATIONS: How many superseded extractor generations sweep_superseded keeps behind the current one by default: one.
DEFAULT_MEMORY_SCOPE: The scope recorded when a caller names none.
DEFAULT_MIN_LINES: The default min_lines floor for debt_density: files shorter than this are counted but not ranked (see DebtDensityReport::min_lines for why the floor exists at all).
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.
FINDING_KEY_PREFIX: The prefix of every FindingKey.
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.
MAX_ANALYZER_ID: Longest permitted analyzer id, in characters. Real analyzer ids are short (cargo-audit, semgrep, trivy.fs); the bound exists because an analyzer id is a component of both a layer key and every finding key, and those are stored, indexed and printed.
MAX_IDENTITY_PART: Longest permitted identity component, in bytes. Identity parts are rule ids, paths, offsets and digests; anything longer is a malformed or hostile report, not a finding, and is refused before it can bloat the store.
MAX_MEMORY_BODY: Longest permitted memory body, in bytes. Generous, because a body is prose — a failure write-up with a stack trace in it is a legitimate memory. Anything past this is a file being pasted into a database, not a lesson.
MAX_MEMORY_SCOPE: Longest permitted scope, in bytes. A scope is a short label — a branch name, a worktree id, a project — not a sentence.
MEMORY_SCHEMA: Stable schema tag on MemoryListing, so a programmatic consumer can depend on the shape.
ORACLE_SCHEMA: Stable schema tag for the oracle report.
RECALL_SCHEMA: Stable schema tag on Recall.
SCHEMA: The versioned schema tag emitted on every query result. Bump the version on any breaking change to the shape.
SECURITY_LAYER_PREFIX: The layer-key prefix under which every findings layer is filed.
TOOL_CONTEXT_EDGE_CAP: The largest number of edges a tool_context bundle carries per direction.

Traits§

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

Functions§

analyzer_id_error: The rejection message for an analyzer id that is_valid_analyzer_id refuses: which rule it broke, then the whole contract.
anchor_penalty: What a record’s anchor is worth as a ranking multiplier, in [0.0, 1.0].
build_context: Build a node’s context bundle from the current graph (ignoring the cache). Returns None if no node has that key.
cache_budget_bytes: The configured cache budget in bytes: CACHE_BUDGET_ENV megabytes if it is set, otherwise DEFAULT_CACHE_BUDGET_BYTES.
canonicalize_config_key: Canonicalise a dotted key for cross-naming-convention matching: keep the dotted structure, but collapse each .-delimited segment to its lowercased ASCII-alphanumerics only — dropping _, -, and any other punctuation within the segment. So within a segment serverEndpoint, server_endpoint, and server-endpoint all become serverendpoint, letting a Kubernetes YAML zerobus.serverEndpoint (camelCase) match an app TOML zerobus.server_endpoint (snake_case) that normalize keeps apart — normalize splits on any run of non-ASCII-alphanumeric chars, so _ becomes a boundary (zerobus.server.endpoint) and a compound leaf never lines up with its camelCase spelling. The dotted structure is preserved here (segments are split on . only) so a.b and ab stay distinct.
cap_content: Trim and cap text to [MAX_CONTENT] characters (whitespace-collapsed), so stored content stays small and deterministic.
compare_codegraph: Compare Roteiro’s derived graph (store) against a codegraph snapshot at db_path, returning an OracleReport. Read-only on both sides.
config_secrets: Inventory the secret-named config keys in the graph — where they are, what they are called, and whether their values were redacted before persistence — capped at limit (0 = unlimited).
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.
coupling: Rank nodes by directed call coupling — fan-in (distinct callers) and fan-out (distinct callees) over Calls edges — most-coupled first by order, capped at limit (0 = unlimited).
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.
debt_density: Rank files by intent-debt density — retained markers per 1,000 lines — most-dense first by order, capped at limit (0 = unlimited). categories and ignore filter markers exactly as debt does, so the two lenses always agree about which markers exist.
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.
first_h1: The visible text of the first # heading in md, or None when there is none — including a # that opens an empty heading, which names nothing and so defers to whatever fallback the caller has (a slug, a file stem, ADR-nnnn).
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).
heading_text: The visible text of a heading whose Markdown source content is source — the part after the ## , with the markup that produced it removed.
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_prose: Whether path is a prose file whose body is worth embedding.
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.
is_tooling_config_path: Whether a repo-relative config path is build / tooling / CI config rather than an application’s own config — a Cargo.toml, a rustfmt.toml, a CI workflow, and so on. Used only by opt-in filters (--app-config-only, the explorer’s “hide tooling config” toggle): the default everywhere is to show every config key, so this classifier never changes what is extracted or stored.
is_valid_analyzer_id: Whether id is a well-formed analyzer id: 1..=MAX_ANALYZER_ID characters, every one of them lowercase [a-z0-9] or one of ., _, -.
layer_key: Render the layer key a findings layer is filed under: security:<analyzer>:<worktree-id>.
list_kind: List every node of the given kind, ordered by key.
markdown_dialect: The Markdown dialect this project reads and renders with — the one answer to “what does this source mean”, for every surface that asks.
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.
release_media_engines: Destroy the process-wide media engines (vision, ASR) that extraction loaded and then the llama.cpp backend they shared, returning whether anything was released.
search: Deterministically search nodes for query, ranked by relevance, returning at most limit hits — or every match when limit == 0, which is window’s rule and the one every list lens follows (issue #393). An empty result therefore always means “nothing matched”, never “you asked for nothing”.
search_channels: Search every channel: the graph, and — each only when asked for — model-generated media content and episodic agent memory.
slugify: A URL-safe slug: lowercase, non-alphanumeric runs collapsed to a single -, trimmed of leading/trailing -.
sweep_superseded: Delete the object-cache entries left behind by superseded extractor generations, keeping the current one and keep_generations behind it.
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).
tool_context: A node’s context bundle for a model-facing tool surface: read-only and bounded. Returns None if no node has that key.
window: Cut an already-ordered, already-materialised list down to the window a caller asked for: skip offset items from the front, then keep at most limit.

Crate rto_graph

Crate rto_graph Copy item path

Re-exports§

Modules§

Structs§

Enums§

Constants§

Traits§

Functions§

Crate rto_graph