🥮 mooncakes.io
README

colmugx/acp/connection does not have a README file

#
ConnectionError

source
type ConnectionError derive(Eq, 
Debug)

Reducer failures are structured and never converted into silent defaults.

#
RuntimeOwnerError

source
pub(all) suberror RuntimeOwnerError {
  Closed
} derive(Eq, 
Debug)

#
ConnectionCancelIgnoreReason

source
type ConnectionCancelIgnoreReason derive(Eq, 
Debug)

The precise, closed reason set for one tolerated inbound wire cancellation. An ACP $/cancel_request is best-effort by wire contract: the receiver MAY cancel the matching activity, the only obligation is that the original request still receives its response, and the contract is silent on ids that were never seen or already settled. Real ACP clients routinely send cancels that lose the race with an already-delivered response, so every well-formed cancel of a non-live id is a traced no-op instead of a connection failure.

#
ConnectionCommand

source
type ConnectionCommand derive(Eq, 
Debug)

Intent-only commands. No command owns an async task, queue, callback, or dependency environment.

#
ConnectionEvent

source
type ConnectionEvent derive(Eq, 
Debug)

Events are data only. Effects are represented by ConnectionCommand in the reducer output and are interpreted by a runtime outside this package.

#
ConnectionPhase

source
type ConnectionPhase derive(Eq, 
Debug)

The lifecycle of a pure connection reducer.

#
ConnectionState

source
type ConnectionState derive(Eq, 
Debug)

All mutable-looking connection data is carried explicitly in this value. The reducer never mutates an input state's arrays; each transition copies and updates its own arrays before returning a new state.

#
ConnectionStep

source
type ConnectionStep derive(Eq, 
Debug)

A pure transition result.

#
PendingInbound

source
type PendingInbound derive(Eq, 
Debug)

A request initiated by the peer and awaiting local handler completion.

#
PendingOutbound

source
type PendingOutbound derive(Eq, 
Debug)

A request initiated by the local endpoint and awaiting its peer.

#
RuntimeOutboundChannel

source
pub struct RuntimeOutboundChannel[C] {
  // private fields
}

Engine-level outbound submission channel for one connection. A submitter deposits one event in the connection's single event queue and parks on a one-shot reply queue; the single owner loop allocates the request id, registers the waiter, and only then offers the write to the serial writer queue (waiter-before-send). The channel is constructed only inside connection_runtime_run_owner_with_outbound; its fields never escape.

#
RuntimeOutboundChannel::submit_notification

source
async fn[C] RuntimeOutboundChannel::submit_notification(self : RuntimeOutboundChannel[C], method_name~ : String, params~ : Json) -> Unit

Submit one notification and park until the engine acknowledges it. The ack records enqueue into the serial writer queue only; it never claims transport I/O completed, matching the ClientNotificationBroker contract on the stable facade.

#
RuntimeOutboundChannel::submit_notification_sync

source
fn[C] RuntimeOutboundChannel::submit_notification_sync(self : RuntimeOutboundChannel[C], method_name~ : String, params~ : Json) -> Result[Unit, 
RuntimeError]

Submit one notification synchronously, without parking on an asynchronous acknowledgement. The submission is a synchronous try_put onto the connection's single event queue — the same primitive every other event-queue publication wraps through runtime_event_put — carrying a fire-and-forget marker instead of a parked ack queue, so a caller that cannot block still submits through the one engine loop rather than a second writer.

Contract: Ok claims only that the event was accepted into the engine's event queue. Writer-offer and transport failures are never reported through this result; they remain observable at the connection level through the loop's fail-and-close semantics (trace sink and runner result), never as a silent success. Failures are the structured EventQueueClosed (also returned after shutdown, before enqueueing) and EventQueueBackpressure(limit~) errors, exactly like runtime_event_put.

#
RuntimeOutboundChannel::submit_request

source
async fn[C] RuntimeOutboundChannel::submit_request(self : RuntimeOutboundChannel[C], method_name~ : String, params~ : Json) -> 
JsonRpcResponse

Submit one request and park until the engine delivers exactly one reply. Submission is rejected with EventQueueClosed before enqueueing once the engine has begun shutting down, mirroring the owner task publication guard: a parked submitter can never outlive the loop, because admitted waiters are released by the close sweep and never-admitted submissions are answered by the engine's stranded-event drain.

#
RuntimeOwner

source
pub struct RuntimeOwner[S, I] {
  state : S
  tasks : Array[RuntimeOwnerTask[I]]
  next_task_token : Int
  closed : Bool
}

Immutable owner state. A single runtime owner must serialize all calls to admission, cancellation, completion, and close. No Ref, lock, or second reader/writer/reducer loop is needed.

#
RuntimeOwner::is_closed

source
fn[S, I] RuntimeOwner::is_closed(self : RuntimeOwner[S, I]) -> Bool

#
RuntimeOwner::state

source
fn[S, I] RuntimeOwner::state(self : RuntimeOwner[S, I]) -> S

#
RuntimeOwner::task_count

source
fn[S, I] RuntimeOwner::task_count(self : RuntimeOwner[S, I]) -> Int

#
RuntimeOwnerCancelResult

source
pub(all) enum RuntimeOwnerCancelResult[S, I, C] {
  RuntimeOwnerCancelRequested(owner~ : RuntimeOwner[S, I], task~ : RuntimeOwnerTask[I], event~ : RuntimeOwnerEvent[C])
  RuntimeOwnerCancelIgnored(reason~ : RuntimeOwnerIgnore)
}

Cancellation marks the task and returns the typed cancellation completion as an event. The owner applies that event through the same completion path, which releases the reservation exactly once; a late handler event is then ignored by token.

#
RuntimeOwnerCloseResult

source
pub(all) enum RuntimeOwnerCloseResult[S, I] {
  RuntimeOwnerClosed(owner~ : RuntimeOwner[S, I], aborted~ : Array[RuntimeOwnerTask[I]])
  RuntimeOwnerAlreadyClosed(owner~ : RuntimeOwner[S, I])
}

#
RuntimeOwnerCommand

source
pub(all) enum RuntimeOwnerCommand {
  RuntimeOwnerWriteNotification(notification~ : 
JsonRpcNotification)
  RuntimeOwnerCancelInbound(request_id~ : 
RequestId)
  RuntimeOwnerTrace(method_name~ : String)
  RuntimeOwnerClose(reason~ : String)
} derive(Eq, 
Debug)

Connection-owned pure commands compiled from owner effects. These values are intents only; the runtime does not execute or interpret them here. The RuntimeOwner prefix keeps their constructors distinct from the connection reducer's event and command constructors. The eventual owner interpreter supplies fixed trace fields from the method name; no arbitrary payload or trace text crosses this boundary.

#
RuntimeOwnerCompletionResult

source
pub(all) enum RuntimeOwnerCompletionResult[S, I, O] {
  RuntimeOwnerCompletionApplied(owner~ : RuntimeOwner[S, I], completion~ : O)
  RuntimeOwnerCompletionIgnored(reason~ : RuntimeOwnerIgnore)
}

#
RuntimeOwnerEffect

source
pub(all) enum RuntimeOwnerEffect[E] {
  WireNotification(notification~ : 
JsonRpcNotification)
  Local(effect~ : E)
} derive(Eq, 
Debug)

A connection-owned effect produced by a pure completion. Wire notifications are transport values; local effects are caller-defined data for the owner to interpret. Neither variant executes an effect here.

#
RuntimeOwnerEvent

source
pub(all) enum RuntimeOwnerEvent[C] {
  RuntimeOwnerRequestCompleted(token~ : Int, id~ : 
RequestId, completion~ : C)
  RuntimeOwnerNotificationCompleted(token~ : Int, completion~ : C)
}

A completion event produced by an immutable async invocation. The event contains only its owner token, correlation id (for requests), and typed completion. It cannot carry or mutate connection state.

#
RuntimeOwnerIgnore

source
pub(all) enum RuntimeOwnerIgnore {
  Closed
  UnknownTask(token~ : Int)
  UnknownRequest(id~ : 
RequestId)
  AlreadyCancelled(id~ : 
RequestId)
  RequestIdMismatch(expected~ : 
RequestId, actual~ : 
RequestId)
  TaskKindMismatch(token~ : Int)
} derive(Eq, 
Debug)

#
RuntimeOwnerLocalPlan

source
pub(all) enum RuntimeOwnerLocalPlan {
  RuntimeOwnerNoCommands
  RuntimeOwnerCommands(Array[RuntimeOwnerCommand])
} derive(Eq, 
Debug)

Explicit result of local-effect planning. RuntimeOwnerNoCommands is an intentional no-command plan; RuntimeOwnerCommands preserves every planned command in order. An empty commands array is still explicit, but callers should use RuntimeOwnerNoCommands when no command is intended.

#
RuntimeOwnerNotificationAction

source
pub(all) enum RuntimeOwnerNotificationAction[S, I, E] {
  RuntimeOwnerNotificationImmediate(completion~ : RuntimeOwnerNotificationCompletion[S, E])
  RuntimeOwnerNotificationInvoke(task~ : RuntimeOwnerTask[I])
}

#
RuntimeOwnerNotificationAdmission

source
pub(all) enum RuntimeOwnerNotificationAdmission[S, I, E] {
  RuntimeOwnerNotificationImmediate(completion~ : RuntimeOwnerNotificationCompletion[S, E])
  RuntimeOwnerNotificationInvoke(state~ : S, invocation~ : I)
}

A synchronous admission result for a notification. Notifications never carry a request id or response; immediate notifications still commit their state and effects synchronously.

#
RuntimeOwnerNotificationCompletion

source
pub(all) struct RuntimeOwnerNotificationCompletion[S, E] {
  state : S
  effects : Array[RuntimeOwnerEffect[E]]
}

A notification completion commits domain state and effects but has no response field, so the owner cannot accidentally reply to a notification.

#
RuntimeOwnerPort

source
pub(all) struct RuntimeOwnerPort[S, I, C, E] {
  initial_state : S
  admit_request : (S, 
RequestId, 
JsonRpcRequest) -> RuntimeOwnerRequestAdmission[S, I, E]
  admit_notification : (S, 
JsonRpcNotification) -> RuntimeOwnerNotificationAdmission[S, I, E]
  execute : async (I) -> C
  execute_failure : (S, I) -> C
  execute_cancel : (S, I) -> C
  complete_request : (S, 
RequestId, I, C) -> RuntimeOwnerRequestCompletion[S, E]
  complete_notification : (S, I, C) -> RuntimeOwnerNotificationCompletion[S, E]
  plan_local_effect : (E) -> RuntimeOwnerLocalPlan
  cancel_request : (S, 
RequestId, I) -> (S, C)
  abort : (S, RuntimeOwnerTask[I]) -> S
}

The one-shot generic owner hooks. The connection runtime or another connection-local owner loop invokes these callbacks synchronously while it owns S; only execute crosses the async boundary.

#
RuntimeOwnerRequestAction

source
pub(all) enum RuntimeOwnerRequestAction[S, I, E] {
  RuntimeOwnerImmediate(completion~ : RuntimeOwnerRequestCompletion[S, E])
  RuntimeOwnerInvoke(task~ : RuntimeOwnerTask[I])
}

#
RuntimeOwnerRequestAdmission

source
pub(all) enum RuntimeOwnerRequestAdmission[S, I, E] {
  RuntimeOwnerRequestImmediate(completion~ : RuntimeOwnerRequestCompletion[S, E])
  RuntimeOwnerRequestInvoke(state~ : S, invocation~ : I)
}

A synchronous admission result for a request handled by a generic connection owner. An immediate result commits the complete owner step synchronously; an invoke commits state before the invocation is handed to an async task. The task never receives the owner.

#
RuntimeOwnerRequestCompletion

source
pub(all) struct RuntimeOwnerRequestCompletion[S, E] {
  state : S
  response : 
RuntimeHandlerResult
  effects : Array[RuntimeOwnerEffect[E]]
}

A request completion commits domain state together with exactly one wire result and zero or more owner effects. Requests cannot represent multiple responses through this type.

#
RuntimeOwnerTask

source
pub struct RuntimeOwnerTask[I] {
  task_token : Int
  request_id : 
RequestId?
  invocation : I
  notification : Bool
  cancel_requested : Bool
}

The immutable task record owned by one connection owner loop. Its invocation is caller-defined typed data; no queue, task group, or mutable state is stored here.

#
RuntimeOwnerTask::cancel_requested

source
fn[I] RuntimeOwnerTask::cancel_requested(self : RuntimeOwnerTask[I]) -> Bool

#
RuntimeOwnerTask::invocation

source
fn[I] RuntimeOwnerTask::invocation(self : RuntimeOwnerTask[I]) -> I

#
RuntimeOwnerTask::is_notification

source
fn[I] RuntimeOwnerTask::is_notification(self : RuntimeOwnerTask[I]) -> Bool

#
RuntimeOwnerTask::request_id

source

#
RuntimeOwnerTask::task_token

source
fn[I] RuntimeOwnerTask::task_token(self : RuntimeOwnerTask[I]) -> Int

#
connection_runtime_run

source

#
connection_runtime_run_owner

source
async fn[S, I, C, E] connection_runtime_run_owner(ports : 
RuntimePorts, options : 
RuntimeOptions, owner_port : RuntimeOwnerPort[S, I, C, E]) -> Unit

#
connection_runtime_run_owner_with_outbound

source
async fn[S, I, C, E] connection_runtime_run_owner_with_outbound(ports : 
RuntimePorts, options : 
RuntimeOptions, channel_factory : (RuntimeOutboundChannel[C]) -> RuntimeOwnerPort[S, I, C, E]) -> Unit

Run the one owner engine with an engine-level outbound submission channel. The factory runs after the connection-local queues and shutdown state exist and before the loop starts; its closures may capture the channel and hand it to typed request/notification brokers in a later work order. This runner adds no second loop: it reuses the same single reader/writer/reducer engine as connection_runtime_run_owner, whose signature and behavior stay unchanged for existing callers.

#
runtime_owner_admit_notification

source
fn[S, I, C, E] runtime_owner_admit_notification(owner : RuntimeOwner[S, I], notification : 
JsonRpcNotification, port : RuntimeOwnerPort[S, I, C, E]) -> (RuntimeOwner[S, I], RuntimeOwnerNotificationAction[S, I, E]) raise RuntimeOwnerError

#
runtime_owner_admit_request

source
fn[S, I, C, E] runtime_owner_admit_request(owner : RuntimeOwner[S, I], request : 
JsonRpcRequest, port : RuntimeOwnerPort[S, I, C, E]) -> (RuntimeOwner[S, I], RuntimeOwnerRequestAction[S, I, E]) raise RuntimeOwnerError

#
runtime_owner_cancel_request

source
fn[S, I, C, E] runtime_owner_cancel_request(owner : RuntimeOwner[S, I], id : 
RequestId, port : RuntimeOwnerPort[S, I, C, E]) -> RuntimeOwnerCancelResult[S, I, C]

Mark the exact request as cancelled and synchronously create its typed cancellation completion. The caller may cancel the task after this admission; applying event through runtime_owner_complete_request releases the owner reservation. A late task completion is ignored.

#
runtime_owner_close

source
fn[S, I, C, E] runtime_owner_close(owner : RuntimeOwner[S, I], port : RuntimeOwnerPort[S, I, C, E]) -> RuntimeOwnerCloseResult[S, I]

Close the owner exactly once. Abort callbacks update only the domain state; no wire response is generated here. Any completion carrying an old token is ignored by the closed-owner check.

#
runtime_owner_complete_notification

source
fn[S, I, C, E] runtime_owner_complete_notification(owner : RuntimeOwner[S, I], event : RuntimeOwnerEvent[C], port : RuntimeOwnerPort[S, I, C, E]) -> RuntimeOwnerCompletionResult[S, I, RuntimeOwnerNotificationCompletion[S, E]]

#
runtime_owner_complete_request

source
fn[S, I, C, E] runtime_owner_complete_request(owner : RuntimeOwner[S, I], event : RuntimeOwnerEvent[C], port : RuntimeOwnerPort[S, I, C, E]) -> RuntimeOwnerCompletionResult[S, I, RuntimeOwnerRequestCompletion[S, E]]

#
runtime_owner_execute

source
async fn[S, I, C, E] runtime_owner_execute(task : RuntimeOwnerTask[I], port : RuntimeOwnerPort[S, I, C, E]) -> RuntimeOwnerEvent[C]

Execute only the immutable invocation and return a typed event. This is the only async operation in the generic owner seam.

#
runtime_owner_new

source
fn[S, I, C, E] runtime_owner_new(port : RuntimeOwnerPort[S, I, C, E]) -> RuntimeOwner[S, I]

#
runtime_owner_plan_effects

source
fn[E] runtime_owner_plan_effects(effects : Array[RuntimeOwnerEffect[E]], plan_local_effect : (E) -> RuntimeOwnerLocalPlan) -> Array[RuntimeOwnerCommand]

Compile every owner effect in order without changing owner state. A local effect is expanded by the caller-owned total planner and its commands are appended in place; no effect is dropped or interpreted in this function. This is a pure plan compiler only: it performs no I/O, task cancellation, tracing, or connection close. The real owner runner/interpreter is not wired here yet.

#
runtime_owner_spawn

source
fn[G, S, I, C, E] runtime_owner_spawn(group : 
TaskGroup[G], task : RuntimeOwnerTask[I], port : RuntimeOwnerPort[S, I, C, E]) -> 
Task[RuntimeOwnerEvent[C]]

Start one immutable invocation in the caller's existing task group. The returned task is the only runtime cancellation handle; owner state remains with the caller, which must apply the resulting event serially.

Source Files

Powered by MoonBit

Site sourceReport issuePackagesBuild queueSkillsStatistics

© 2026 mooncakes.io