Crate monoloop_contracts 

SPDX-License-Identifier: AGPL-3.0-or-later Copyright (C) Alexander R. Croft

Shared contracts for Monoloop product components.

Product components share identities, dialect descriptors, canonical events, configuration, transaction ports, and closed error families. This crate intentionally contains no transport, dialect decoder, tool execution, UI, or host-agent logic.

Structs

AdmissionError

Synchronous admission error.

AdmissionReceipt

Immediate admission receipt (no network performed).

Bytes

A cheaply cloneable and sliceable chunk of contiguous memory.

CancellationReason

Cancellation reason.

CanonicalAssistantToolCall

Historical or live assistant tool call embedded in input.

CanonicalInput

Ordered canonical messages for one transaction submission.

CanonicalToolError

Bounded public domain error from a tool.

CanonicalToolResult

Sole continuation/MCP success-domain product.

CanonicalUnitSnapshot

Correlation + lifecycle envelope for one unit generation.

ChannelCapabilities

Declared Channel capabilities (immutable registry data).

ChannelDefaults

Channel default invocation values.

ChannelDescriptor

Data-only Channel descriptor used before live binding construction.

ChannelId

Channel identity (caller-selected; never ambient).

ChannelLimits

Per-Channel capacity and encoding bounds.

ConnectionId

Local logical transport attachment identity for one connection scope.

ConnectorError

Connector error with safe, bounded diagnostics.

ConnectorLimits

Connector-level limits applied at open.

ContinuationContext

Immutable continuation context: original input plus required tool turns.

DeliveryLimits

Validated event-queue capacities for transaction_delivery.

DiagnosticCode

Safe diagnostic code (closed vocabulary preferred; free-form codes are bounded).

DialectBinding

Immutable input/output dialect pair for one opened connection.

DialectDescriptor

Stable, bounded, versioned dialect descriptor.

EffectiveConfig

Immutable effective configuration after merge.

EncodedExchange

Encoded provider exchange body.

ExchangeId

One provider request/response exchange inside a transaction.

ExtensionKey

Namespaced extension key (e.g. openai.seed).

ExtensionLimits

Extension map bounds (invocation and session configuration).

ExternalSessionId

Opaque externally owned session identity (e.g. Grok sessionId).

FlowId

Flow identity (one logical dialect exchange/response).

FnCompletionCallback

Closure adapter for CompletionCallback.

FnEventSink

Closure adapter for TransactionEventSink.

GrokSessionId

Grok Build’s authoritative sessionId — the sole session correlation identity for the Grok connector profile.

InitialEncodeRequest

Initial outbound encode request (no live handler objects).

InputLimits

Bounds for validating crate::input::CanonicalInput.

InterpretationEnd

Exactly one terminal report per interpretation.

InterpretationId

Interpretation instance identity.

InterpretationLimits

Interpretation assembly and output bounds.

InterpreterError

Interpreter error with safe diagnostics.

InvocationConfig

Per-request invocation overrides (never secrets or endpoints).

JsonSchema

JSON Schema document for tool input/output (object root required).

LaneId

Lane identity within a flow.

LoopEnd

Exactly one Loop terminal report.

LoopError

Loop error with safe diagnostics.

LoopId

Loop instance identity.

LoopLimits

Aggregate Loop bounds.

LoopScope

Explicit Loop admission scope (no ambient expansion).

ModelDiagnostic

Safe model/dialect diagnostic.

MonoloopRunId

Monoloop run correlation identity.

OptionPolicy

Which options a Channel accepts and which are immutable once a session exists.

OutboundToolResult

Provider-neutral outbound tool result (Loop product; not dialect-encoded).

ParagraphBoundary

Paragraph open/close.

RequestId

Caller/request correlation identity (opaque, no authority).

SafeDiagnostic

Bounded safe diagnostic attached to terminals, cancellations, and events.

SemanticBoundary

Semantic boundary (not turn/task completion authority).

SessionConfig

External-agent session configuration (no prompt, MCP URL, or secrets).

SessionId

Caller-visible session / correlation identity for transaction routing.

SessionKey

Session exclusion and session-directed control key.

ShutdownDisposition

Shutdown summary counts.

ShutdownReport

Final shutdown report when the runtime reaches Stopped (v2).

ShutdownSnapshot

Point-in-time shutdown progress while still Quiescing (v2).

SourceTimeObservation

Dialect-observed source time for a complete (or lifecycle) unit.

StructuralAtom

Non-sentence structural atom.

TerminationReason

Force-termination reason.

TextPart

Non-empty text content part.

TextSentence

Complete sentence atom (immutable after emission).

ToolActionEvent

Tool-action event payload.

ToolActionId

Tool action identity (dialect-provided or interpretation-scoped).

ToolCall

Provider-neutral tool call arguments at dispatch time.

ToolCallContext

Correlation context for a tool invocation (no prompts or secrets).

ToolContinuationEncodeRequest

Tool-result continuation encode request.

ToolExecutionId

Stable tool execution identity within one Loop incarnation.

ToolId

Stable host-registry tool identity (selection key on requests).

ToolLimits

Per-tool execution bounds.

ToolName

Tool name as exposed to models / MCP (distinct from ToolId).

ToolOutputContract

Output contract for a registered tool.

ToolSpec

Immutable tool specification (no handler).

TransactionCompletion

One-shot completion mailbox payload (v2).

TransactionCompletionReceiver

Host-held one-shot completion receiver.

TransactionCompletionSender

Runtime-held one-shot completion sender (consumed exactly once).

TransactionDelivery

Ports installed at admission and owned by the lifecycle ledger until publish.

TransactionDiagnostic

Bounded safe transaction diagnostic.

TransactionEnd

Terminal transaction result.

TransactionEndEvent

Terminal event body for the v2 event stream (no self-referential delivery).

TransactionEvent

Ordered transaction event.

TransactionEventReceiver

Host-held half of the event mailbox.

TransactionEventSender

Runtime-held half of the event mailbox.

TransactionId

Admitted transaction identity (Monoloop-generated, never reused).

TransactionLimits

Runtime transaction bounds (see implementation §12).

TransactionReceiver

Host receivers created together with TransactionDelivery.

TransactionSubmitRequest

Runtime v2 submission request — concrete mailboxes, no host traits in-core.

TransactionUsage

Bounded usage facts (unavailable is not zero).

TransportBufferLimits

Input/output buffer bounds for one connection.

UnitId

Stable unit identity within one interpretation.

UsageObservation

Usage observation (unavailable is not zero).

VersionedExtension

Versioned extension payload.

Enums

AdmissionErrorKind

Admission error kinds.

BoundaryKind

Boundary kinds.

CancellationReasonCode

Cancellation reason codes.

CanonicalMessage

One typed canonical message.

CanonicalToolOutput

Canonical successful or domain-failed tool output body.

CanonicalToolResultOutcome

Success or declared domain failure (not a runtime failure).

CanonicalUnit

Closed top-level canonical unit vocabulary.

CanonicalUnitEvent

Unit lifecycle event (closed vocabulary).

ChannelCapabilityError

Channel capability validation error.

ChannelKind

Whether the Channel talks to an external agent or a direct LLM API.

CleanupFailureCode

Closed cleanup failure codes (v2).

CleanupStatus

Status of owned cleanup after completion publication (v2).

CompletionDeliveryError

Completion callback delivery error (safe).

CompletionPublishResult

Result of a one-shot completion publication attempt.

ConfigError

Configuration construction / merge error.

ConfigOption

Named configuration option for policy checks.

ConnectorErrorKind

High-level connector error classification.

ContinuationPolicy

How the runtime continues after model tool calls.

DeliveryConfigError

Invalid delivery-port construction.

DiagnosticKind

Diagnostic kinds.

DialectFamily

High-level dialect family (not an encoder/decoder implementation).

DialectNegotiation

How the dialect was selected for a connection.

EncodingError

Encoding failure (maps to EncodingFailed terminal).

EventDeliveryError

Event delivery error (safe).

EventDeliveryOutcome

Terminal event delivery outcome.

EventEnqueueError

Event enqueue failure (fail closed).

ExchangeInputPolicy

Whether the encoded exchange finishes the connection write path.

ExchangeMode

Provider exchange shape.

IdentityError

Identity construction failure (safe, closed).

InputValidationError

Canonical input validation failure.

InterpretationEndKind

Interpretation terminal kinds.

InterpreterErrorKind

Interpreter error classification.

InterpreterOutputEvent

Stream events delivered to subscribers (Interpreter output + end).

LimitsError

Limit configuration rejected before runtime start.

LoopEndKind

Loop terminal kinds.

LoopErrorKind

Loop error classification.

LoopOutputEvent

Closed Loop output event vocabulary (initial).

McpConfigurationCapability

MCP configuration installability on the external agent.

McpReachability

Whether the external agent can reach Monoloop’s MCP listener.

OutboundToolOutcome

Terminal outcome of a loop-owned tool action (provider-neutral).

ParagraphKind

Paragraph boundary kind.

ReasoningEffort

Optional reasoning effort hint (provider-neutral label).

ResponseFormat

Optional response format constraint.

SafeDiagnosticError

Safe diagnostic construction error.

SessionMode

Session topology for the Channel.

ShutdownWaitOutcome

Wait outcome for crate runtime owner shutdown (v2).

StructureKind

Structural kinds recognized for canonical assembly.

TerminalEventDelivery

Outcome of attempting to enqueue the terminal Ended event (v2).

TerminationDisposition

Immediate disposition of a terminate request.

TerminationMode

Termination mode.

TerminationReasonCode

Termination reason codes.

TextChannel

Canonical text channel.

TokenCount

Measured or unavailable count.

ToolCompletion

Completion of a tool execution handle.

ToolContractError

Tool contract construction error.

ToolExecutionClass

Structural execution / termination class for a registered tool (v2 §14).

ToolExecutionMode

How tools execute for transactions on this Channel.

ToolExecutionState

Observed execution state from dialect (not host Loop execution).

ToolLifecycleEvent

Host tool lifecycle event on the transaction stream (not dialect observation).

ToolRequestState

Tool request assembly state.

ToolResultState

Result assembly state.

ToolRuntimeError

Runtime failure from a tool implementation.

ToolStartError

Failure starting a linked tool handler.

ToolSuccessContract

Declared successful tool output shape.

ToolTerminalOutcome

Terminal tool outcome as observed in the dialect (not host tool runtime).

ToolUnavailableReason

Why a tool was unavailable.

TransactionEndKind

Closed terminal kinds.

TransactionEventPayload

Event payload variants.

TransactionSelector

How to address an in-flight transaction for control.

UnitState

Lifecycle state of a canonical unit.

Constants

MAX_IDENTITY_BYTES

Maximum bytes for opaque string identities and tool names.

Traits

CompletionCallback

One-shot completion callback.

OutboundDialectEncoder

Outbound dialect encoder port (implemented in monoloop-loop adapters).

TransactionEventSink

Caller event sink (push-based).

Functions

estimate_canonical_input_bytes

Deterministic admission byte estimate covering every canonical field (D-035).

estimate_event_bytes

Conservative byte estimate for queue accounting (not wire encoding).

merge_effective_config

Merge: Channel defaults <- session configuration <- permitted invocation overrides.

send_and_retain_allowed

Whether SendAndRetain is legal for this Channel.

transaction_delivery

Create paired delivery ports with validated capacities.

user_text_input

Helper to build a single-user-text input under default limits.

validate_identity_string

Validate a bounded opaque identity string.

Type Aliases

CompletionDelivery

Future returned by completion callback.

EventDelivery

Future returned by event delivery (no async_trait required).

Shutdown

Shutdown future type.