Crate themql_core 

themql-core

Canonical owner of theMQL’s core type identities: Message, Query, Response, Error, Context, and Resource identity.

Every other crate in theMQL is subordinate to this one for type definitions. See specs/core.toml for the authoritative specification.

Authority

Per SPEC.toml and prompts/SYSTEM.md, the canonical types here are the semantic owners. Transport adapters (themql-mqtt, themql-graphql, themql-sse) project these types; they do not redefine them.

Example

use themql_core::{Message, MessageId, Subject, Operation, Payload,
                   Metadata, Timestamp, TimestampKind};

let subject = Subject::from_str("vehicle.sensors.imu.gyro")
    .expect("valid subject");
let msg = Message {
    id: MessageId::new(),
    timestamp: Timestamp::now_monotonic(),
    subject,
    operation: Operation::Telemetry,
    payload: Payload::Unit,
    metadata: Metadata::default(),
};
assert_eq!(msg.operation, Operation::Telemetry);

Structs

CachePolicy

Policy controlling how a Query result is cached. Carried in Context and optionally overridden on Query.cache_policy.

Cancellation

Cancellation signal propagated through the resolution chain. A resolver must check cancellation before returning a result and return ErrorCode::Timeout if cancelled.

CausationId

Links an Event back to the Command that caused it. Required on Events; optional elsewhere.

Context

Execution context propagated through every query resolution and command dispatch. Carries deadline, auth principal, trace id, cache policy, and cancellation signal.

CorrelationId

Links a Response (or error) back to the Query/Command that caused it. Required on Responses; optional on commands/events.

Deadline

Absolute deadline for a Query resolution or Command dispatch. Carried in Context. Resolvers must check the deadline before returning a result and return Error with code ErrorCode::Timeout if exceeded.

Error

The canonical error type. Transport adapters project this into GraphQL errors, MQTT error topics, SSE error frames, etc. Transport adapters must not define their own error types.

FieldPath

A dot-joined path into a resource (e.g. position.x).

Message

The fundamental primitive. Every request, command, event, stream, response, telemetry reading, and error is carried by a Message.

MessageId

Unique identifier for a Message. Wraps a UUID v7 (monotonic-ish).

Metadata

Key-value bag carried on every Message. Holds correlation id, causation id, trace id, auth principal, format hint, and arbitrary extension keys.

Principal

Auth principal carried in Metadata.

Projection

Optional field projection narrowing which fields of each selected entity appear in the Response. Combined with Selection, this completes the ‘filter + projection’ shape.

Query

A read-only, side-effect-free request against a named Resource. A Query is always carried inside a Message with operation = Query.

Resource

A named, addressable entity in theMQL. Every Query targets a Resource. Resources have a hierarchical identity (a Subject).

Response

The result of a Query or Command. Carried inside a Message with operation = Response. A Response contains either a value or an Error; never both, never neither.

Subject

A concrete, hierarchical, dot-separated routing key.

SubjectPattern

A Subject that may contain wildcards. Used for subscriptions and cache invalidation patterns, never as a concrete Message.subject.

SubjectSegment

A single non-empty segment of a Subject.

Timestamp

Timestamp on every Message. Tagged explicitly so consumers know whether to trust it for ordering.

TraceId

Trace identifier for distributed tracing.

Enums

CacheTier

Tier of the cache stack.

Comparison

Comparison operator for a selection predicate.

ErrorCode

Canonical error code. Transport adapters project this into GraphQL errors, MQTT error topics, SSE error frames, etc.

FormatTag

Tag identifying the serialisation format of a payload.

InvalidationHint

Hint to the cache about when to invalidate an entry.

Operation

The verb of a Message. Tags payload semantics.

PatternSegment

A single segment of a SubjectPattern.

Payload

Explicitly typed, serde-serialisable payload of a Message. The format is tagged in the payload itself (never inferred from transport).

Predicate

A boolean predicate tree over resource fields.

ResponseValue

The value carried by a successful Response. Mirrors Payload but is a distinct type so transports can project independently.

Selection

Optional filter predicate selecting a subset of a resource. Combined with Projection, this forms the ‘filter + projection’ shape: a Query with selection = All returns all entities of the resource; selection = Filter(p) narrows which entities are returned.

SubjectError

Errors raised while constructing or parsing Subject / SubjectPattern.

TimestampKind

Kind of timestamp — monotonic vs wall-clock.

Traits

MessageHandler

Handler for incoming messages.

QueryExecutor

Orchestrator around Resolver: applies caching, batching, deadline propagation, and cancellation checks. Declared here so transport adapters can depend on the trait without a hard dep on themql-query; implemented in themql-query.

Resolver

Resolver for queries against a resource. Implementations are domain-specific (storage, analysis, telemetry).

ResolverBoxed

Blanket adapter: any Resolver whose resolve returns a Send future can be boxed into dyn Resolver.