Expand description
§blazingly-contract
Runtime-neutral, canonical API contracts for Blazingly.
The crate owns the semantic source of truth shared by HTTP, MCP, AI documentation, internal RPC, and future mesh tooling:
- versioned canonical encoding independent of declaration order;
- model, input, output, typed-error, dependency, and security metadata;
- aliases, nested validation, and stable custom-validator identities;
- pull-based streaming request-body inputs without a runtime dependency;
- MCP discovery and agent risk, confirmation, and idempotency policies;
- SHA-256 contract fingerprints;
- semantic compatibility reports.
It intentionally does not depend on Tokio, an HTTP server, an MCP transport,
proc macros, or runtime dependency injection. The default std feature can be
disabled for no_std + alloc consumers.
use blazingly_contract::{Compatibility, OperationContract};
fn verify_upgrade(previous: &OperationContract, current: &OperationContract) {
let report = Compatibility::compare(previous, current);
assert!(report.is_backward_compatible());
println!("{}", current.fingerprint());
}The Rust API follows Semantic Versioning. Canonical bytes and fingerprints are additionally
versioned by CURRENT_CONTRACT_FORMAT_VERSION; changing the crate version does
not silently change a contract fingerprint.
Version 0.4 uses canonical format 1.3, which carries value-type constraints
on TypeDescriptor, including collection items and nested values, while
preserving deterministic ordering and compatibility classification. Every
operation fingerprint changes across the 1.2 to 1.3 move, so recorded
compatibility baselines have to be recaptured. The new public constraints
field breaks a struct literal that names every TypeDescriptor field: use
TypeDescriptor::scalar/model/new, or add constraints: Vec::new().
§Install
[dependencies]
blazingly-contract = "0.4"Licensed under the MIT License.
Structs§
- Agent
Policy - Protocol-neutral metadata used by MCP and other agent transports.
- Compatibility
- Entry point for semantic contract comparison.
- Compatibility
Change - One deterministic compatibility finding.
- Compatibility
Report - Semantic compatibility report between two versions of one operation.
- Contract
Fingerprint - Stable SHA-256 identity of one canonical operation contract.
- Contract
Format Version - Version of the canonical Blazingly contract format.
- Dependency
Descriptor - A typed dependency declared by an operation handler.
- Field
Descriptor - One field in an API model.
- Field
Violation - One typed model-validation failure.
- Input
Descriptor - One typed operation argument and its HTTP extraction source.
- Invalid
Operation Id - An invalid operation identity.
- McpTool
Descriptor - MCP tool semantics declared alongside an operation.
- Model
Descriptor - A complete model used by validation,
OpenAPI, MCP, and Markdown. - Operation
Contract - The protocol-neutral semantic contract for one operation.
- Operation
Failure - A typed domain failure shared by HTTP and MCP projections.
- Operation
Id - A stable, human-readable operation identity such as
users.create. - Response
Build Error - A response construction failure that must be redacted by transports.
- Response
Descriptor - A single successful or error response declared by an operation.
- Response
Header - A response header emitted without transport-specific dependencies.
- Security
Requirement - Security scheme and scopes required by one operation.
- Security
Scheme Descriptor - Named security scheme registered by an application.
- Type
Descriptor - The type identity and schema captured by the Rust frontend.
- Validation
Errors - All model-validation failures collected in one pass.
Enums§
- Compatibility
Impact - Compatibility impact of one semantic contract change.
- Confirmation
- Whether an agent must ask for confirmation before invoking an operation.
- Input
Source - The transport-neutral source of one operation argument.
- Operation
Risk - Agent-visible risk associated with invoking an operation.
- Output
Exposure - How much operation output may be exposed to an agent.
- Schema
Kind - Transport-independent JSON shape.
- Security
Location - HTTP location used by an API-key security scheme.
- Security
Scheme Kind - Transport-independent description of an application security scheme.
- Validation
Rule - Validation generated as native Rust code by
#[api_model].
Constants§
- CURRENT_
CONTRACT_ FORMAT_ VERSION - The current canonical contract encoding version.