Crate mant_query 

mant-query

Bounded semantic queries over existing ManT document snapshots. This crate selects content, projects outlines and references, searches canonical content, and collects independent explanation evidence. It does not discover sources, load files, resolve remote documents, render reports, or modify input IR.

Existing content in, query results out

Single-document operations borrow mant_ir::ResolvedContent. Requests and versioned response DTOs belong to mant-protocol; original document nodes, typed locations, identities and reference scanning belong to mant-ir.

use mant_ir::{Document, ResolvedContent};
use mant_protocol::OutlineNode;
use mant_query::build_outline;

// The caller already has IR: no source parser or loader is needed here.
let document: Document = serde_json::from_value(serde_json::json!({
    "source": { "format": "markdown" },
    "meta": {},
    "sections": [{
        "id": "usage",
        "heading": { "content": [{ "type": "text", "value": "Usage" }] },
        "blocks": [],
        "children": []
    }]
}))?;
let content = ResolvedContent {
    label: "demo".to_owned(),
    address: None,
    document: Some(document),
    tldr: None,
};
let outline = build_outline(&content)?;
assert!(matches!(
    outline.nodes.as_slice(),
    [OutlineNode::DocumentSection { title, .. }] if title == "Usage"
));

Content selection uses explicit paths or IDs, never name guessing. Explain is a separate evidence query: repeated names produce independent evidence, not a first-match selection. Classification, global order, paging and content-copy budgets remain explicit in the result, including partial coverage.

Collections without a loader dependency

QueryScopeView::new validates a borrowed logical graph against its ordered content slice. It checks address and traversal consistency without cloning, loading or serializing the documents. Callers retain ownership and must supply one coherent snapshot; this validation does not prove remote freshness. search_scope and explain_scope share global query budgets and pagination.

Use mant-loader to acquire content when needed, or compose an application’s complete request with mant-engine. Neither is a dependency of this package. Query errors stay separate from source acquisition and host delivery errors.

Format boundary

Markdown-scope search uses the canonical Markdown artifact and source mapping from mant-codec, with native features disabled. Its text and ranges refer to the same borrowed source snapshot. This format dependency does not enable native parsing or report rendering. Reference destination checks inspect typed logical addresses and already supplied content only; they perform no IO.

See the protocol manual for process contracts and the IR manual for authoritative content ownership. The crate is Apache-2.0 licensed.

Structs

QueryScopeView

An immutable graph and its exact, ordered content snapshots.

ReferenceProjectionLimits

Independent reference operation budgets; input-file size is not a substitute.

ResolvedContent

One materialized document query before any versioned process projection.

SelectorCandidate

One exact path offered when a content ID has multiple owners.

Enums

ExplanationError

Invalid explanation request or missing readable source.

ProjectionError

Failure to derive an addressable view from a complete query.

ScopeExecutionError

Query failures independent of catalog resolution and source I/O.

ScopeInputError

Invalid association between a logical loading report and supplied content.

SearchError

Invalid search input or matcher construction.

Functions

build_outline

Build a block-free, addressable outline for one complete query.

build_outline_projection

Build a structural outline with an explicit semantic-entry projection.

build_outline_with_detail

Build an outline with optional semantic definition entries.

build_outline_with_references

Project exact local content and independently scan its real references.

explain_query

Collect independent semantic and literal evidence without unique selection.

explain_scope

Explain across existing snapshots with global classification and paging. No catalog lookup, parsing or source acquisition is performed.

project_references

Project selected original links without catalog I/O or implicit document loading. Invalid policies return an unscanned inventory; process boundaries validate first.

project_references_with_limits

Project under explicit hard-clamped budgets, including all skipped offset work.

resolve_explanation_block

Resolve an explanation block/preview coordinate in the exact queried IR.

search_query

Search one complete query and report coordinates in its canonical Markdown.

search_scope

Search existing snapshots with one global result cursor. No loading or parsing occurs; coverage remains in the supplied graph.

select_excerpt

Select tldr, document-root content, or complete section subtrees by path or ID.

select_explanation

Collect semantic evidence with the documented default page/copy budgets. Use explain_query for explicit pagination; use crate::select_excerpt for strict node navigation. No-evidence is a normal response.

semantics_complete

Whether all producers and shared validators permit a complete projection. Consumers must not infer this effect from diagnostic severity, text or codes.

validate_explanation_query

Validate literal and copy bounds before loading any source.

validate_search_query

Validate search limits and compile its matcher without loading a manual.