Crate mant_protocol

Expand description

§mant-protocol

mant-protocol is ManT’s transport-neutral interaction boundary. It defines query contracts and projections shared by in-process hosts, CLI JSON, request JSON, and compact MCP presentation without owning any transport. It owns schema markers, logical catalog addresses, pagination, outline, excerpt, search, tldr-update results, local doctor reports, deterministic catalog presentation, and JSON Schema generation. The mant crate separately composes host callbacks, process framing, terminal policy, and MCP transport.

Use this crate whenever a Rust host or process consumer needs stable inputs, projections, or deterministic non-terminal presentation. The same DTO may cross an in-memory callback, be serialized by a versioned JSON boundary, or be rendered into a compact MCP result; serialization is a supported representation, not the crate’s sole purpose. It performs no document discovery, parsing, query execution, terminal I/O, or MCP transport.

§Contract families

QueryRequest ──> host / mant-engine ──┬─> QueryBundle
                                     ├─> QueryOutline
                                     ├─> QueryExcerpt
                                     └─> QuerySearch

ScopeQueryRequest ──> host / mant-engine ──> ScopeQueryResponse

CatalogQuery ──> host ──────────────────> DocumentCatalog ──> compact text

local inspection ───────────────────────> DoctorReport

Family	Current discriminator	Purpose
Process framing	`mant.cli/v0.9`	Advertised by the `mant` executable
Request	`mant.request/v0.9`	Closed input accepted by `--request-json`
Scope request/result	`mant.scope-request/v0.9`, `mant.scope-query/v0.9`	Bounded multi-document search and explanation
Full query	`mant.query/v0.9`	Document plus optional tldr content
Document	`mant.document/v0.9`	Versioned projection of the normalized document
Catalog	`mant.catalog/v0.9`	Registered Markdown and native-manual discovery
Outline, excerpt, search	`mant.outline/v0.9`, `mant.excerpt/v0.9`, `mant.search/v0.9`	Focused query projections
Doctor	`mant.doctor/v1`	Read-only local installation diagnostics

The schemas generated from the Rust types are authoritative. Request schemas are generated for deserialization so closed-object and default behavior match what the process accepts; response schemas are generated for serialization. These native schema discriminators describe CLI and request JSON. MCP uses its own negotiated protocol version and presents the same logical identities and focused projections as bounded text or CommonMark instead of serializing the native response envelopes.

§Basic use

Construct requests with the typed tagged unions and discover the exact JSON Schema rather than copying a shape by hand:

use mant_protocol::{
    NATIVE_API_VERSION, OutlineDetail, QueryInput, QueryRequest, QueryView,
    RequestSchema, query_request_json_schema,
};

let request = QueryRequest {
    schema: RequestSchema::V0Dot9,
    input: QueryInput::Document {
        selector: "git".to_owned(),
        source: None,
        manual_section: None,
    },
    view: QueryView::Outline {
        detail: OutlineDetail::Entries,
    },
};

assert_eq!(NATIVE_API_VERSION, "0.9");
assert_eq!(request.schema, RequestSchema::V0Dot9);
let _schema = query_request_json_schema();

The native query family follows ManT’s pre-stable minor release line: ManT 0.9.x uses v0.9, and patch releases retain the same wire shape. The former bare v1 through v7 schemas were experimental and are intentionally not accepted by 0.9. Historical tags preserve those contracts; the first stable native protocol will use a v1.0 release line. Independent contracts such as mant.doctor/v1 and mant.markdown/v1 keep their own identifiers. Clients must therefore compare complete discriminators. The mant-protocol crate has its own semver; upgrading that Rust package does not by itself select a new wire discriminator.

Adding or changing a Rust field does not by itself authorize a wire change. The native discriminator must advance whenever its serialized contract changes outside a patch-compatible addition.

mant-protocol deliberately reuses the semantic Block, Section, Inline, DefinitionIdentity, DocumentAddress, source, metadata, diagnostic, and tldr types from mant-ir. Those types form the wire-bearing semantic subset: a Serde change to any of them is also a protocol change. CI compares every generated structural schema with the checked-in v0.9 snapshot, so an accidental IR representation change fails until compatibility is restored or the affected protocol discriminator is advanced explicitly. Rustdoc descriptions and schema titles are excluded from that structural comparison.

Focused excerpt and search results share OutlineTrail: ordered compact ancestors plus one typed terminal node. This keeps full tree-chain rendering and machine navigation consistent without treating exact explanation as a text search.

Normalized document content is defined separately by mant-ir. Parsing, lookup, projection, and rendering live in mant-engine. The complete wire contract is documented by mant-protocol(5). Compatibility and migration notes are recorded in the crate changelog.

§License

Apache-2.0.

Structs§

CatalogCoverage: Indexed namespaces available to one catalog query.
CatalogMatchScore: Complete literal relevance score shared by catalog frontends.
CatalogQuery: Bounded filtering and pagination shared by CLI, TUI, and MCP discovery.
DoctorCheck: One independently actionable installation check.
DoctorEnvironment: Effective local paths and host identity inspected by mant --doctor.
DoctorReport: Complete read-only installation health report.
DoctorSummary: Stable counts for one complete doctor run.
DocumentCatalog: Deterministically ordered page of discoverable local documents.
DocumentEdge: One resolved edge in source order.
DocumentFrontier: One typed outbound link excluded by a traversal bound.
DocumentResponse: Serializable v0.9 envelope around ManT’s protocol-independent document IR.
DocumentScope: Initial documents and the link policy used to expand them.
DocumentSelector: One logical document selector before catalog resolution.
DocumentSummary: One catalog row identified entirely by logical names.
DocumentTraversal: Bounded traversal applied after resolving the initial documents.
Engine: Parser implementation recorded at the process boundary.
NodePath: Canonical structural address emitted for a node in a projected outline.
NodeSelector: User-supplied outline selector interpreted as a path, node ID, or entry alias.
OutlineReference: Compact ancestor identity attached to an excerpt selection.
OutlineTrail: Complete logical location of one addressable document node.
Producer: Identifies ManT and the parser used to build a wire document.
QueryBundle: Versioned full-query result emitted at CLI and request JSON boundaries.
QueryExcerpt: One or more independently selected nodes from a complete query.
QueryOutline: A block-free tree used to discover selectable query content.
QueryRequest: Native use-case input. The engine validates semantic constraints before I/O.
QuerySearch: Complete, paginatable search result returned to agents and scripts.
ResolvedDocumentScope: Logical graph produced before applying a projection.
ScopeQueryRequest: Native request for a bounded multi-document query.
ScopeQueryResponse: Complete bounded multi-document response.
ScopeSearch: Globally paginated search over a resolved document scope.
ScopedDocument: One distinct document in breadth-first traversal order.
ScopedExplanation: One successful semantic-entry selection in a document scope.
ScopedQueryFailure: One per-document projection failure that does not invalidate other results.
ScopedSearchDocument: One document’s search hits inside a globally paginated scope result.
SearchContextLine: One rendered Markdown line surrounding a match.
SearchHit: One rendered line or line span containing one or more exact occurrences.
SearchLineRange: One exact occurrence fragment within an anchor-free rendered Markdown line.
SearchMarkdownRange: Half-open byte range plus one-based human coordinates in full Markdown.
SearchOccurrence: One exact matcher occurrence in the canonical Markdown render.
SearchQuery: Normalized search configuration echoed in a search response.
SearchRender: Description of the deterministic document whose Markdown coordinates are reported.
TldrCacheUpdate: Result of an explicit mant --update-tldr operation.
UnresolvedDocument: A seed or typed link that could not be resolved.

Enums§

CatalogDocumentKind: Optional family filter for catalog discovery.
CatalogMatchRank: Stable relevance tier for literal catalog matching.
CatalogSchema: Exact schema marker for a local document catalog.
CatalogSpellingRank: Spelling fidelity inside one catalog relevance tier.
DoctorCheckStatus: Severity of one stable doctor check.
DoctorOutcome: Aggregate health derived from every doctor check.
DoctorSchema: Exact schema marker for an installation health report.
DocumentAddress: Stable selector for one discoverable document candidate.
DocumentEdgeKind: Typed cross-document edge retained in a resolved scope.
DocumentSchema: Exact schema marker for a normalized structured document response.
ExcerptSchema: Exact schema marker for selected query content.
ExcerptSelection: One selected document node together with its location in the complete outline.
InputFormat: Parser selected for an explicit physical input.
MarkdownOrigin: Storage identity of one registered Markdown document.
MarkdownSchema: Markdown contract used as the coordinate space for every search format.
OutlineDetail: Amount of semantic detail included in an outline projection.
OutlineNode: One uniquely addressable node in a query outline.
OutlineNodeReference: Compact typed identity for the terminal node in an OutlineTrail.
OutlineSchema: Exact schema marker for a query outline response.
QueryInput: Source selected by one public query request.
QuerySchema: Exact schema marker for a complete ManT query result.
QueryView: Projection requested after loading one complete structured document.
RequestSchema: Exact schema marker for a native query request.
ScopeQueryResult: Projection result carried by a scope-query response.
ScopeQuerySchema: Exact schema marker for a resolved scope query.
ScopeQueryView: Query projection supported over a document set.
ScopeRequestSchema: Exact schema marker for a scope-query request.
ScopeTextError: One violated runtime constraint shared by scope-query request adapters.
SearchCase: Case-folding policy applied when compiling the matcher.
SearchRenderFormat: Canonical render format used for search coordinates.
SearchRenderScope: Amount of the query included in the coordinate-bearing render.
SearchSchema: Exact schema marker for structure-aware search results.
SearchScope: Text representation searched while Markdown remains the coordinate basis.
SearchSyntax: Pattern language used for one search.
TldrCacheAction: How an explicit tldr cache refresh changed local state.
TraversalLimit: Traversal bound that excluded an outbound logical link.

Constants§

CLI_PROTOCOL_VERSION: Exact process protocol reported by the native CLI boundary.
DEFAULT_SCOPE_DEPTH: Default maximum number of link edges followed from an initial document.
DEFAULT_SCOPE_DOCUMENT_LIMIT: Default maximum number of distinct documents in one resolved scope.
DEFAULT_SEARCH_LIMIT: Default maximum number of matching line groups returned in one page.
MAX_DOCUMENT_SELECTOR_BYTES: Maximum UTF-8 byte length of one logical document selector.
MAX_SCOPE_CONTENT_BYTES: Maximum aggregate normalized-document payload retained by one scope.
MAX_SCOPE_DEPTH: Hard maximum number of link edges accepted by the native scope contract.
MAX_SCOPE_DOCUMENTS: Maximum number of initial documents accepted by the native scope contract.
MAX_SCOPE_DOCUMENT_LIMIT: Hard maximum number of distinct documents in one resolved scope.
MAX_SEMANTIC_ENTRY_BYTES: Maximum UTF-8 byte length of one semantic-entry selector.
NATIVE_API_VERSION: Pre-stable native API release line shared by the query protocol family.

Functions§

catalog_literal_match_rank: Rank one document name or slash-delimited path using the catalog’s literal-search case policy.
catalog_literal_match_score: Rank one literal candidate while preferring case-faithful spellings inside the same exact, prefix, or substring tier.
default_catalog_limit: Return the default maximum number of catalog rows.
default_scope_depth: Return DEFAULT_SCOPE_DEPTH.
default_scope_document_limit: Return DEFAULT_SCOPE_DOCUMENT_LIMIT.
default_search_limit: Return DEFAULT_SEARCH_LIMIT.
doctor_report_json_schema: Generate the read-only installation health report schema.
document_catalog_json_schema: Generate the local document-catalog JSON representation.
query_bundle_json_schema: Generate the complete-query JSON representation emitted by mant.
query_excerpt_json_schema: Generate the selected-excerpt JSON representation emitted by mant.
query_json_schema_catalog: Generate every public request and query-response contract in stable order.
query_outline_json_schema: Generate the outline JSON representation emitted by mant.
query_request_json_schema: Generate the JSON representation accepted when deserializing a request.
query_search_json_schema: Generate the structure-aware search result emitted by mant.
render_catalog_coverage_text: Explain why an empty catalog query selected no indexable scope.
render_catalog_text: Render a catalog page as stable, unstyled text.
sanitize_terminal_text: Replace control characters in dynamic text before terminal presentation.
scope_query_request_json_schema: Generate the bounded multi-document request representation.
scope_query_response_json_schema: Generate the bounded multi-document result representation.
validate_scope_text: Validate one bounded logical selector at the native request boundary.