Skip to content
DocumentationCommunication
On this page

Page resources

Open Markdownllms.txtView source

Last updated

Communication

Communication begins when information crosses an execution boundary. One models the meaning of that crossing before choosing HTTP, QUIC, a queue, a broker, shared memory, a process pipe, or an in-process call.

Operations do not imply a network

An operation owns its request, response, domain faults, effects, deadlines, cancellation, idempotency, authority, and evidence. Planning may realize the same operation as a static call, a task boundary, a local process, a remote request, or managed external service.

Each descent adds only the necessary physical contracts. A remote call adds identity, codec, addressing, transport security, discovery, routing, backpressure, delivery, retry, observation, and cost. If the edge returns local, those requirements disappear from the next plan.

Delivery words have exact meanings

At-most-once, at-least-once, effectively-once, ordered, unordered, durable, replayable, and best-effort are separate contracts. They are qualified by the boundary, acknowledgement point, lease, cursor, retention, and failure model.

An acknowledgement may mean that a peer received bytes, accepted a command, durably appended it, applied a state transition, or observed a postcondition. One records which. Earlier acknowledgement never implies a later phase.

Failure is part of the interface

Deadlines and cancellation propagate through structured execution. Retry policy includes attempts, budgets, backoff, jitter, idempotency, deduplication, and the point after which an outcome may be unknown. Hedging is a separate multi-dispatch effect and is admitted only when duplicate work is safe.

Circuit breaking, load shedding, rate limits, queue credits, buffer bounds, and admission control preserve finite resources. Backpressure is carried to the producer wherever the selected protocol supports it; otherwise the plan must name the bounded loss or spill policy.

Streams retain time and flow

Streams describe item framing, ordering, cursor semantics, gaps, replay, overflow, credits, cancellation, half-close, and terminal outcomes. A stream is not modeled as an endless sequence of unrelated unary calls.

Offline and intermittently connected paths add local intent, bounded leases, conflict rules, synchronization cursors, data classification, and convergence evidence. A disconnected device does not inherit online authority forever.

Protocols are removable realizations

Protocol adapters map owned communication contracts to established systems. They retain the exact mapping and any loss without moving application meaning into the protocol.

Negotiation selects only compatible, admitted schema, codec, transport, and security revisions inside the plan's envelope. Runtime negotiation cannot download new code, broaden authority, or escape the released closure.

Example

Illustrative end-product syntax projects an operation only at the edge:

operation parcelhub.tracking#GetShipment@1
    request GET "/shipments/{shipment_id}"
    result 200 json(output)
    fault ShipmentNotFound -> 404 json(fault)

Follow Project HTTP and streaming. For queues and event delivery, follow Project operations to messaging.

Canonical owner: Communication.

Next: workflows and agents.