Crate prov_graph 

prov-graph

The read core of a prov workspace: plaintext documents, the links declared in their own embedded metadata, and the traversal over them.

What this crate is for

A prov workspace describes itself. Follow the links in a document’s frontmatter and body and the whole structure unfolds — no index to trust instead of the documents, no sidecar folder that has to be kept in step. This crate is that unfolding, and only that.

Everything here reads. The filesystem port it asks for (fs::ReadStorage) has no method that writes a byte; the id index it asks for (index::IdIndex) has no method that changes a registration. Nor is the vocabulary for writing merely unused — it is absent, declared a layer up in prov-store instead. So a consumer that must not modify a workspace — a language server, a static renderer, a browser viewer — can depend on this crate and be unable to, rather than merely intending not to. That is the whole reason the split exists, and it is why the write halves are not here behind a feature flag someone could leave switched on.

The write surface is prov-store: Storage, the metadata editor, and the IndexStore registries. The verbs are prov: creating, renaming, deleting, attaching, the change/journal machinery that makes a mutation crash-atomic, the version history, the config layer, the validation and repair passes. prov owns one Graph and forwards every read to it, so the two are the same traversal — not a reimplementation that can drift.

prov-views is what that promise looks like taken up: a whole view engine — parse a declared view, resolve its scope by walking the spanning relation, group the documents it reaches — built on this crate and nothing else, and therefore unable to modify a byte of what it reads.

The shape of it

• Document — a plaintext file split into its embedded metadata block and its body.
• relation::RelationSet — which metadata fields are links. Exactly one may be spanning: the single-parent tree that gives a workspace its discovery spine. Every other relation may be many-to-many, so the tree is a backbone, never a ceiling.
• Graph — a root, a fs::ReadStorage, an index::IdIndex, and the graph::ReadSettings that say how links are spelled. Its two walks are the census (every forward link, flat, each tagged with where it is written and how it resolves) and the tree (the spanning relation only, as a materialized outline).

The census is ground truth. Reachability, the backlinks map, and prov’s own validation findings are all views over it, and any stored index heals toward it, never the reverse.

Re-exports

pub use content::ContentFormat;

pub use content::code_spans;

pub use content::render_html;

pub use document::Document;

pub use document::EmbedStyle;

pub use document::MetaCarrier;

pub use document::embed_carrier;

pub use document::embed_style_of;

pub use document::is_opaque_payload;

pub use document::require_whole_file;

pub use error::Error;

pub use error::Result;

pub use exec::block_on;

pub use fs::DirEntry;

pub use fs::FileType;

pub use fs::Metadata;

pub use fs::ReadStorage;

pub use fs::StdFs;

pub use graph::Backlink;

pub use graph::CensusEntry;

pub use graph::Graph;

pub use graph::LinkSite;

pub use graph::Node;

pub use graph::NodeKind;

pub use graph::ReadSettings;

pub use graph::Resolution;

pub use graph::StructuralFact;

pub use graph::Target;

pub use graph::TreeOptions;

pub use graph::Walk;

pub use graph::reachable_set;

pub use identity::Id;

pub use identity::IdStorage;

pub use index::Collision;

pub use index::IdIndex;

pub use index::NoIndex;

pub use link::Addressing;

pub use link::BodyLink;

pub use link::Link;

pub use link::LinkStyle;

pub use link::Notation;

pub use link::PathStyle;

pub use link::ReferenceStyle;

pub use link::Wikilink;

pub use link::Wrapper;

pub use link::escapes_root;

pub use link::format_link;

pub use link::is_valid_workspace_id;

pub use link::path_to_title;

pub use manifest::Manifest;

pub use manifest::ManifestEntry;

pub use manifest::manifest_sibling;

pub use memo::ReadScope;

pub use meta::Mapping;

pub use meta::Value;

pub use peer::NoPeers;

pub use peer::PeerLocation;

pub use peer::PeerLookup;

pub use peer::PeerResolver;

pub use peer::Unconfirmed;

pub use relation::Cardinality;

pub use relation::Edge;

pub use relation::Relation;

pub use relation::RelationSet;

pub use title::TitleIndex;

pub use title::TitleMatch;

Modules

content

Body-prose parsing via twig — prov’s answer to the content_format knob deferred in docs/next-steps.md, and the ingredient that makes body-link findings code-aware (DESIGN §8’s principle: a [[…]] that is really code, e.g. [[inf] * n for _ in range(m)]] inside backticks, must never be treated as a link).

document

Documents — a plaintext file with an embedded metadata block and a body, or a config file whose entire content is the metadata.

error

Error and result types.

exec

A dependency-free executor for backends whose futures are already ready.

fs

prov’s filesystem port.

graph

Plain text → walkable graph — the crate’s read core.

identity

Identity — the id type, and what makes one well-formed.

index

Index — where stable IDs and (later) the materialized graph live.

link

Link text — the raw strings a relation field holds, the wikilinks embedded in body prose, and the path arithmetic around them.

manifest

Manifests — one node standing for a whole directory of opaque files.

memo

A read memo with the lifetime of one operation — the cheap half of not reading the same file twice.

meta

Embedded-metadata values — a dynamic, order-preserving value tree over fig.

peer

prov’s peer port — where the other workspaces are.

relation

Relations — the configurable vocabulary of links declared in metadata.

title

Title index — the derived name → document map that resolves nominal (“alias”) references like [[My File]].

Enums

EmbedType

The embed archetype a fenced metadata block was found in. Re-exported from fig, which owns both detection (fig::detect) and the fence/format coupling (EmbedType::inner_format). Which embedded config to open — the flat mirror of fig’s parametric Embed.Type. The three parametric families (markdown ---<lang> frontmatter, ```<lang> fenced blocks, <script type> HTML data islands) are enumerated once per format. The first four names are historical (FrontmatterJson is the ;;; block, FrontmatterFig is the ```fig fenced block); the rest are grouped by container.

ExtKind

The kind of a format-specific Value::Extended scalar. Mirrors the core’s ExtKind and the C ABI’s FigExtKind; the discriminants match that ABI.

Format

A config format. Every variant parses, edits, and serializes.