Crate soothfast_docs 

Soothfast docs engine.

Four rot channels, four mechanisms:

• signatures can’t rot: the API surface is read from rustdoc JSON (surface, reference, diff);
• prose can’t rot silently: bind blocks fingerprint the code they describe, locked in soothfast.lock (markdown, lockfile);
• examples can’t rot: every markdown rust block becomes a generated test, capture blocks become runnable examples (gentests);
• numbers can’t rot: quantitative claims in prose evaluate against the latest measurement baseline (claims).

Modules

claims

Quantitative-claims ledger: item.backend.metric <op> value[unit] evaluated against a measurement baseline. Numbers in prose become gated facts instead of aspirations.

diff

Public-surface diff between two builds: what a reviewer needs to see about API-relevant change, and the raw material for changelog drafting.

gentests

Generated artifacts from markdown code blocks: one integration-test target per package with a module per page (plain rust blocks), and one example per package with a module per capture block. CI compares regenerated content against disk, so stale artifacts fail.

lockfile

soothfast.lock: committed fingerprints for every bound item. A bind is stale when the item’s current fingerprint differs from the locked one; docs accept re-locks after the prose has been re-verified by a human.

markdown

Line-based markdown scanning: fenced code blocks with info tags, and <!-- soothfast:... --> markers. Deliberately not a markdown AST — we need fences and comment markers only (dependency policy: no pulldown-cmark).

reference

API reference fragments: per-crate markdown generated from the surface — literal source signatures + doc comments, enriched with measured costs and verified claims from the baseline. Regenerated on demand so the reference cannot be stale: every number on the page was produced, never written.

surface

Public API surface from rustdoc JSON: item paths, span-derived fingerprints, doc presence, and literal source signatures.