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

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.