Crate mant_protocol

Expand description

§mant-protocol

mant-protocol is ManT’s versioned structured interaction boundary. It defines the request and response DTOs shared by in-process hosts, CLI JSON, request JSON, and MCP without owning any transport. It owns schema markers, logical catalog addresses, pagination, outline, excerpt, search, tldr-update results, and JSON Schema generation. The mant crate separately composes host callbacks, process framing, and MCP transport.

Use this crate whenever a Rust host or process consumer needs stable structured inputs and projections. The same DTO may cross an in-memory callback or a serialized transport; serialization is a supported representation, not the crate’s sole purpose. It contains data contracts only: it performs no document discovery, parsing, query execution, rendering, terminal I/O, or MCP transport.

§Contract families

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

CatalogQuery ──> host ──────────────────> DocumentCatalog

Family	Current discriminator	Purpose
Process framing	`mant.cli/v7`	Advertised by the `mant` executable
Request	`mant.request/v7`	Closed input accepted by `--request-json`
Full query	`mant.query/v7`	Document plus optional tldr content
Document	`mant.document/v7`	Versioned projection of the normalized document
Catalog	`mant.catalog/v7`	Registered Markdown and native-manual discovery
Outline, excerpt, search	`mant.outline/v7`, `mant.excerpt/v7`, `mant.search/v7`	Focused query projections

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.

§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::V7,
    input: QueryInput::Document {
        selector: "git".to_owned(),
        source: None,
        manual_section: None,
    },
    view: QueryView::Outline {
        detail: OutlineDetail::Entries,
    },
};

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

Adding or changing a Rust field does not by itself authorize a wire change. Each schema family advances only when its serialized contract requires it; clients must compare complete discriminators rather than infer compatibility from the ManT package version.

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 v7 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.

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).

§License

Apache-2.0.

Structs§

CatalogQuery: Bounded filtering and pagination shared by CLI, TUI, and MCP discovery.
DocumentCatalog: Deterministically ordered page of discoverable local documents.
DocumentResponse: Serializable v7 envelope around ManT’s protocol-independent document IR.
DocumentSummary: One catalog row identified entirely by logical names.
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.
Producer: Identifies ManT and the parser used to build a wire document.
QueryBundle: Versioned full-query result emitted at JSON and MCP 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.
SearchContextLine: One rendered Markdown line surrounding a match.
SearchMarkdownRange: Half-open byte range plus one-based human coordinates in full Markdown.
SearchMatch: One exact occurrence and both of its structural and rendered locations.
SearchQuery: Normalized search configuration echoed in a search response.
SearchRender: Description of the deterministic document whose Markdown coordinates are reported.
SearchSectionReference: Addressable containing section for a non-tldr match.
TldrCacheUpdate: Result of an explicit mant --update-tldr operation.

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.
DocumentAddress: Stable selector for one discoverable document candidate.
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.
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.
SearchCase: Case-folding policy applied when compiling the matcher.
SearchNode: Nearest node accepted by mant --node for a matching occurrence.
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.

Constants§

DEFAULT_SEARCH_LIMIT: Default maximum number of search matches returned in one page.
NATIVE_API_VERSION: Native API version negotiated independently from document schema versions.

Functions§

catalog_literal_match_rank: Rank one document name or slash-delimited path using the catalog’s literal-search case policy.
default_catalog_limit: Return the default maximum number of catalog rows.
default_search_limit: Return DEFAULT_SEARCH_LIMIT.
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.