Skip to content

vox-kb-facets API Reference (generated)

Crate: vox-kb-facets · Version: 0.6.0 · Target: Library (lib.rs)

L0 KB facet contract: facet types, eligibility rule, summary block, provenance validators, taxonomy and backlog (KB Phase 4).

L0 KB facet contract (KB Phase 4, D-01).

Pure: no I/O and no hashing. Lint, indexer, MENS builder and the generated schema all read facets through this crate, so a doc cannot be eligible in one consumer and ineligible in another.

ModuleDescription
backlog—
frontmatter—
keys—
provenance—
summary—
taxonomy—
StructDescription
SourceOne entry of sources[]; every field is optional so a gap is a lint error, not a parse error.
FacetsTyped KB facets read from page frontmatter. Unknown frontmatter keys are ignored.
EnumDescription
AuthorshipWho wrote the page.
OriginHow the page entered the KB.
KbTierWhich collection the page belongs to: Vox docs or the general library.
TrustTierTrust level of the page; same wire strings as ContextTrustTier.
ScopeWhether the page is about Vox internals or external subject matter.
SensitivityEgress sensitivity; private pages must not leave the machine.
FunctionDescription
parse_facetsParse facets from a whole document. No --- fence at all or an empty block is Facets::default() (grandfathered, D-05). A fence that is opened but not recognised (unterminated, indented, preceded by a blank line) or holds an invalid facet value is an Err: callers must treat it as “not eligible”, never as “no facets” (CR-01).
is_valid_attestationTrue when human_attested_by names a person: non-blank and not a placeholder or AI name (case-insensitive, whole value).
forced_training_ineligibleTrue when the page is forced training-ineligible: web-promoted or LLM-authored content with no valid human_attested_by ([is_valid_attestation]).
effective_training_eligibleThe one shared MENS eligibility rule (D-05, D-06): not forced-ineligible and the flag, which defaults to true.
facet_json_schemaDraft-07 JSON Schema for [Facets] (the GUI type and the 04-03 golden read this).
Dependency Topology, diagram 15 nodes, 4 edges: vox-cli-research → vox-kb-facets; vox-corpus → vox-kb-facets; vox-doc-pipeline → vox-kb-facets; vox-search → vox-kb-facetsvox-kb-facetsvox-cli-researchvox-corpusvox-doc-pipelinevox-search
Diagram source
graph {
direction: right
node vox_kb_facets: "vox-kb-facets"
node vox_cli_research: "vox-cli-research"
vox_cli_research -> vox_kb_facets
node vox_corpus: "vox-corpus"
vox_corpus -> vox_kb_facets
node vox_doc_pipeline: "vox-doc-pipeline"
vox_doc_pipeline -> vox_kb_facets
node vox_search: "vox-search"
vox_search -> vox_kb_facets
}
Consumer CrateRole
vox-cli-researchDirect workspace dependent
vox-corpusDirect workspace dependent
vox-doc-pipelineDirect workspace dependent
vox-searchDirect workspace dependent
KindSymbolSignatureSourceDescription
enumAuthorshippub enum Authorshipcrates/vox-kb-facets/src/lib.rs#L34-L38Who wrote the page.
enumOriginpub enum Origincrates/vox-kb-facets/src/lib.rs#L43-L46How the page entered the KB.
enumKbTierpub enum KbTiercrates/vox-kb-facets/src/lib.rs#L51-L54Which collection the page belongs to: Vox docs or the general library.
enumTrustTierpub enum TrustTiercrates/vox-kb-facets/src/lib.rs#L59-L64Trust level of the page; same wire strings as ContextTrustTier.
enumScopepub enum Scopecrates/vox-kb-facets/src/lib.rs#L69-L72Whether the page is about Vox internals or external subject matter.
enumSensitivitypub enum Sensitivitycrates/vox-kb-facets/src/lib.rs#L77-L80Egress sensitivity; private pages must not leave the machine.
structSourcepub struct Sourcecrates/vox-kb-facets/src/lib.rs#L85-L96One entry of sources[]; every field is optional so a gap is a lint error, not a parse error.
structFacetspub struct Facetscrates/vox-kb-facets/src/lib.rs#L103-L136Typed KB facets read from page frontmatter. Unknown frontmatter keys are ignored.
fnparse_facetspub fn parse_facets(doc_text: &str) -> Result<Facets, String>crates/vox-kb-facets/src/lib.rs#L142-L155Parse facets from a whole document. No --- fence at all or an empty block is Facets::default() (grandfathered, D-05). A fence that is opened but not recognised (unterminated, indented, preceded by a blank line) or holds an invalid facet value is an Err: callers must treat it as “not eligible”, never as “no facets” (CR-01).
fnis_valid_attestationpub fn is_valid_attestation(s: &str) -> boolcrates/vox-kb-facets/src/lib.rs#L187-L190True when human_attested_by names a person: non-blank and not a placeholder or AI name (case-insensitive, whole value).
fnforced_training_ineligiblepub fn forced_training_ineligible(f: &Facets) -> boolcrates/vox-kb-facets/src/lib.rs#L195-L206True when the page is forced training-ineligible: web-promoted or LLM-authored content with no valid human_attested_by ([is_valid_attestation]).
fneffective_training_eligiblepub fn effective_training_eligible(f: &Facets) -> boolcrates/vox-kb-facets/src/lib.rs#L211-L213The one shared MENS eligibility rule (D-05, D-06): not forced-ineligible and the flag, which defaults to true.
fnfacet_json_schemapub fn facet_json_schema() -> serde_json::Valuecrates/vox-kb-facets/src/lib.rs#L217-L229Draft-07 JSON Schema for [Facets] (the GUI type and the 04-03 golden read this).
structbacklog::BacklogRowpub struct BacklogRowcrates/vox-kb-facets/src/backlog.rs#L14-L17One excused doc: exact repo-relative path (/ separators) and the rule ids it is excused from.
structbacklog::Backlogpub struct Backlogcrates/vox-kb-facets/src/backlog.rs#L22-L27The backlog file. Rows are sorted by path, rule ids sorted within a row.
fnbacklog::from_yaml_strpub fn from_yaml_str(s: &str) -> Result<Backlog, String>crates/vox-kb-facets/src/backlog.rs#L35-L67Parse and validate. Every problem is reported, joined with newlines.
fnbacklog::rules_forpub fn rules_for(&self, rel_path: &str) -> Option<&[String]>crates/vox-kb-facets/src/backlog.rs#L71-L76Rule ids excused for the exact repo-relative path, or None when the doc is not listed.
fnbacklog::from_violationspub fn from_violations(crates/vox-kb-facets/src/backlog.rs#L81Build a backlog from live violations (path -> rule ids). Empty sets are dropped; rows and rule ids come out sorted (BTree order), so output is deterministic.
fnbacklog::to_yaml_stringpub fn to_yaml_string(&self) -> Result<String, String>crates/vox-kb-facets/src/backlog.rs#L102-L109The committed file text: generated-file header, serde body, trailing newline.
fnbacklog::tightenedpub fn tightened(crates/vox-kb-facets/src/backlog.rs#L114Removal-only update (D-04): drop rules that are now clean, rows with no rules left and rows whose doc is gone. A live (path, rule) pair this backlog does not list is an addition and returns Err with those pairs. Epoch and note are kept.
fnbacklog::tighten_only_violationspub fn tighten_only_violations(crates/vox-kb-facets/src/backlog.rs#L158Gate the head backlog against the base one: without a re-epoch it may only shrink. base == None is bootstrap (no backlog at the base ref yet). base_docs is every doc path that exists in the base tree: a re-epoch may re-seed over those, but never list a doc that did not exist there (D-03: a new doc is never excused, WR-01).
fnfrontmatter::frontmatter_rangepub fn frontmatter_range(text: &str) -> Option<Range<usize>>crates/vox-kb-facets/src/frontmatter.rs#L53-L55Byte range of the leading --- frontmatter block, from offset 0 through the end of the closing --- line (terminator included). None when the text does not start with --- (after an optional BOM) or the block is never closed.
fnfrontmatter::frontmatter_yamlpub fn frontmatter_yaml(text: &str) -> Option<&str>crates/vox-kb-facets/src/frontmatter.rs#L59-L61The YAML between the opening and closing fence lines (fences excluded), if the block is closed.
structkeys::KeyNearMisspub struct KeyNearMisscrates/vox-kb-facets/src/keys.rs#L36-L41An unknown frontmatter key that looks like a misspelling of a known facet key.
fnkeys::guards_eligibilitypub fn guards_eligibility(&self) -> boolcrates/vox-kb-facets/src/keys.rs#L46-L48True when the intended key decides MENS eligibility.
fnkeys::facet_key_near_missespub fn facet_key_near_misses(doc_text: &str) -> Vec<KeyNearMiss>crates/vox-kb-facets/src/keys.rs#L90-L107Unknown top-level frontmatter keys that look like misspelled facet keys. Empty when there is no closed frontmatter block or it is not a mapping (parse_facets reports those).
fnprovenance::is_blake3_content_hashpub fn is_blake3_content_hash(s: &str) -> boolcrates/vox-kb-facets/src/provenance.rs#L19-L22True for blake3: plus exactly 64 lowercase hex characters (encoded form only).
fnprovenance::is_iso_datepub fn is_iso_date(s: &str) -> boolcrates/vox-kb-facets/src/provenance.rs#L26-L49True for a real Gregorian date written exactly YYYY-MM-DD.
fnprovenance::quote_word_countspub fn quote_word_counts(doc_text: &str, sources: &[Source]) -> Vec<usize>crates/vox-kb-facets/src/provenance.rs#L56-L80Word count of each quote on the page: one entry per contiguous blockquote run in the body (outside fences) plus one per non-empty sources[].quote.
enumsummary::SummaryStatuspub enum SummaryStatuscrates/vox-kb-facets/src/summary.rs#L20-L26Result of inspecting a doc for its summary block (lines are 1-based in the whole doc text).
fnsummary::is_summary_marker_linepub fn is_summary_marker_line(line: &str) -> boolcrates/vox-kb-facets/src/summary.rs#L30-L33True when the line, trimmed, is an HTML or MDX summary open or close marker.
fnsummary::is_esm_import_or_export_linepub fn is_esm_import_or_export_line(line: &str) -> boolcrates/vox-kb-facets/src/summary.rs#L37-L43True when a trimmed line is a top-level ESM import or export statement in MDX.
fnsummary::is_mdx_boilerplate_linepub fn is_mdx_boilerplate_line(line: &str) -> boolcrates/vox-kb-facets/src/summary.rs#L77-L86True when a line outside code fences is MDX/JSX structural noise (import, {/* ... */}, or a standalone Starlight wrapper tag like <Tabs>, <TabItem ...>, <Steps>, <CardGrid>).
fnsummary::strip_mdx_boilerplatepub fn strip_mdx_boilerplate(text: &str) -> Stringcrates/vox-kb-facets/src/summary.rs#L92-L132Strip MDX-only boilerplate (ESM imports/exports, JSX comments {/* ... */}, standalone Starlight wrapper tags, and multi-line <VoxPlayground ... /> embeds) outside fenced code blocks while preserving inner prose and fenced code verbatim.
fnsummary::inspect_summarypub fn inspect_summary(doc_text: &str) -> SummaryStatuscrates/vox-kb-facets/src/summary.rs#L138-L183Locate and measure the summary block. Markers inside fenced code are ignored.
fnsummary::strip_summary_blockspub fn strip_summary_blocks(text: &str) -> Stringcrates/vox-kb-facets/src/summary.rs#L188-L215Remove every summary block (inline forms and MDX {/* kb:summary */} forms included). An open marker with no later matching close removes the rest of the text: fail closed for the MENS strip.
structtaxonomy::Conceptpub struct Conceptcrates/vox-kb-facets/src/taxonomy.rs#L18-L32One vocabulary entry (a domain or a topic).
structtaxonomy::Taxonomypub struct Taxonomycrates/vox-kb-facets/src/taxonomy.rs#L46-L49Validated vocabulary.
enumtaxonomy::LabelMatchpub enum LabelMatch<'a>crates/vox-kb-facets/src/taxonomy.rs#L53-L58How a label resolved.
fntaxonomy::from_yaml_strpub fn from_yaml_str(s: &str) -> Result<Taxonomy, String>crates/vox-kb-facets/src/taxonomy.rs#L106-L183Parse and validate. Every curation problem is reported, joined with newlines.
fntaxonomy::resolve_topicpub fn resolve_topic(&self, label: &str) -> LabelMatch<'_>crates/vox-kb-facets/src/taxonomy.rs#L185-L187—
fntaxonomy::resolve_domainpub fn resolve_domain(&self, label: &str) -> LabelMatch<'_>crates/vox-kb-facets/src/taxonomy.rs#L189-L191—
fntaxonomy::topic_labelspub fn topic_labels(&self) -> Vec<&str>crates/vox-kb-facets/src/taxonomy.rs#L194-L196Topic prefLabels in file order (did-you-mean candidates).
fntaxonomy::domain_labelspub fn domain_labels(&self) -> Vec<&str>crates/vox-kb-facets/src/taxonomy.rs#L199-L201Domain prefLabels in file order.
fntaxonomy::expand_querypub fn expand_query(&self, query: &str) -> Stringcrates/vox-kb-facets/src/taxonomy.rs#L207-L239Append one quoted facet phrase per concept whose altLabel or deprecated alias occurs in the query as a whole token. The phrase targets the card line written by [facet_card_lines], so only facet-tagged cards gain score. Only validated prefLabels are emitted; user text is never rewritten. An odd number of unescaped " returns the query unchanged.