Crate sealmap_corpus

Expand description

§sealmap-corpus

Three jobs: the generated 1:1 Mermaid corpus (below); seal, the lockfile and checks that keep hand-written diagram topics true to the code they cite (sealmap verify); and pack, bounded review packs of topics with the code they cite (sealmap pack).

Projects a Codebase into a contract-enforced, 1:1 corpus of dense Mermaid diagrams plus machine-readable metadata, designed to be read by LLM agents and merged by an orchestrating agent.

§The 1:1 contract

For every source file S in the codebase the corpus contains exactly one document S.md, and nothing else in the corpus claims to describe S. Each document records the BLAKE3 hash of the source it was generated from, so drift is detectable without re-parsing. verify checks the contract against a directory and reports, per file:

Status	Meaning
`Drift::Missing`	source exists, document does not
`Drift::Orphaned`	document exists, source does not
`Drift::Stale`	source changed since the document was generated
`Drift::Modified`	source unchanged but document differs (hand edit, or generator/options changed)

write() brings a directory into compliance (and only ever deletes files that carry the sealmap header); sealmap generate --check runs verify and writes nothing. The corpus is a regenerable view, not a gate.

§What a document contains

src/net/client.rs.md:

YAML front matter: source path, module id, source hash, counts, and the list of fragment ids in the document.
Structure: one classDiagram of everything defined in the file (types with fields/variants/methods, a <<module>> box for free functions, constants and submodules) and their relations (implements, extends, owns, uses), with stubs for types defined elsewhere.
Sequences: one sequenceDiagram per function or method that makes at least CorpusOptions::min_calls calls, rendering its ordered call flow with alt/opt/loop/par fragments.

§Corpus-level files

Reserved names start with _ and never collide with sources:

_index.json: every document and fragment with its participants and the calls it makes, each call linked to the fragment that expands it. This is the merge map for an orchestrator: to inline A’s call into B, look up the call’s expands fragment.
_model.json: the full Codebase (symbols, spans, signatures, docs, relations with confidence).
_overview.md: cross-cutting views: crate/repository dependency graph, per-crate module graphs, data models (erDiagram) and trait maps.
_README.md: how to read all of the above, for agents.

§Stable ids

Every symbol is cited by its sym: id (sym:cargo shop . db/Db#insert()., see sealmap_model::sym) in headings, front matter and the JSON files. Every node, class, entity and participant id is derived from that id by an injective encoding (shop__db___tDb___finsert, see sealmap_mermaid::Ident::from_symbol), so the same symbol has the same id in every diagram of every document, no two symbols share one, and diagrams can be concatenated, merged or diffed by id. generate asserts that uniqueness over the whole codebase.

§Example

use sealmap_corpus::{CorpusOptions, generate};
use sealmap_model::SourceSet;
use sealmap_rust::{RustOptions, extract};

let mut src = SourceSet::new();
src.insert("src/lib.rs", "pub struct A; impl A { pub fn go(&self) { helper(); } }\nfn helper() {}").unwrap();
let model = extract(&src, &RustOptions { name: "demo".into(), ..Default::default() }).codebase;

let corpus = generate(&model, &CorpusOptions::default());
let doc = corpus.document("src/lib.rs.md").unwrap();
assert!(doc.contains("sequenceDiagram"));
assert!(doc.contains("demo___tA->>demo: helper()"));
assert!(corpus.document("_index.json").is_some());

Modules§

pack: Review packs: one deterministic, bounded text holding chosen topics, the dense slice of the code each one cites and a window of that code’s source. An outside reviewer, a seal review or a debugging session reads the pack instead of the repository.
review: Evidence-backed dispositions adjacent to an immutable review export.
route: Portable model-route declarations and fail-closed family checks.
seal: Seals: the record that a hand-written topic was reviewed against exact versions of the code it cites, and the checks that keep that record true.
tiers: Portable per-corpus, per-activity route records.

Structs§

CallRef: One call made by a sequence fragment.
Corpus: A generated corpus: relative output path → file contents, plus the index.
CorpusOptions: Options controlling projection. Every option is part of the output’s identity: changing one changes the documents, which verify reports as Drift::Modified.
DocumentEntry: One document (one per source file).
DriftEntry: One deviation.
FragmentEntry: One diagram inside a document.
Index: The corpus index.
Report: Result of verify / write().

Enums§

Drift: How a corpus file deviates from the contract.
ExternalLanes: How external callees appear as sequence-diagram participants.
FragmentKind: Kind of diagram fragment.

Constants§

CORPUS_SCHEMA_VERSION: Version of the corpus layout, front-matter and _index.json schema.
DOC_SUFFIX: Suffix appended to a source path to name its document.

Functions§

corpus_hash: Hash of a whole corpus (all paths and contents), for cheap equality checks across machines.
document_path: Map a source path to its document path (src/a.rs → src/a.rs.md).
generate: Generate the full corpus in memory. Pure and deterministic: equal inputs give byte-identical output.
is_reserved: true for corpus-level files (_index.json, …).
read_dir_corpus: Read every file under dir (UTF-8 only) keyed by relative path. A missing directory reads as empty.
verify: Verify the corpus in dir against expected.
verify_against: Compare expected (freshly generated) with actual (file path → text as found on disk or elsewhere).
write: Bring dir into compliance with expected: write missing, stale and modified files, delete orphaned generated documents and a sealmap _model.json that expected leaves out (and nothing else). Unchanged files are not touched, so mtimes stay stable. Returns what was changed.