Skip to main content

Crate frame_conv

Crate frame_conv 

Source
Expand description

Conversation patterns over the liminal participant substrate — request-response and subscription (F-3a), pub/sub and the workflow facade (F-3b): the four patterns this crate maps onto conversations so components interact through conversations rather than direct function calls.

§What is here

  • ConversationHandle — the transport-agnostic entry (design D4): no signature names a transport, and the embedded transport arrives later behind these same types.
  • Request-response (frame:conv-request@v1): typed request with a caller-supplied deadline riding the push-side wall; closed outcome set (RequestOutcome); late and duplicate replies have defined, observable fates on the typed anomaly surface (Anomaly).
  • Subscription (frame:conv-subscription@v1): typed events in the substrate’s proven delivery order (SubscriptionItem documents the strength: ordered, contiguous, sender-excluded, membership-forward).
  • The caller-owned resume boundary (ResumeStore, JoinGrant): restore-then-reattach resume replaying the unacked window from the committed cursor (F-0c §R4, proven).
  • Pub/sub (frame:conv-pubsub@v1): caller-minted PublicationId, substrate-only fan-out, O(1) sequence dedup, typed PublicationItem stream with membership news and the typed gap contract (F-3b R1; the A4-superseded honest contract is in the module docs).
  • The workflow pattern (workflow) — one durable conversation as a typed facade over exactly one aion workflow/run lineage (F-3b R2): explicit-key open with the honest weaker idempotency contract, reconstruction from held identity, reopen of terminal reopenable runs, typed contributions, and event-driven observation with the exhaustive progress/terminal projection.

§What is deliberately NOT here (seams named)

  • The embedded transport — a later optimization behind the SAME handle types (design D4); its absence is stated, not implied away.
  • A schema-as-data registry — v1’s schema IS the typed Rust message and validation IS serde at both ends (F-3a R1’s pinned ruling).

§Honest gates carried from the substrate characterization

Characterized at published liminal 0.3.0 (docs/briefs/F-0c-FINDINGS.md) and RE-CHARACTERIZED at published liminal 0.3.1 — the early-car republish, whose 0.3.0→0.3.1 delta is a haematite 0.6.1 repin plus a dropped always-None config field — by re-running this crate’s entire battery, including every live-server suite, green against the =0.3.1 pin (2026-07-21, chore/liminal-031-consume). Every gate below held unchanged at 0.3.1:

  • Peer death surfaces typed, before the deadline (ASK-4 discharged at liminal 0.3.2). Responder death mid-request is delivered, not waited out: the caller observes RequestOutcome::ResponderFailed ahead of the deadline wall, and the subscription stream carries the death exactly once as SubscriptionItem::PeerFailed — one death, one delivery per surface (proven at the socket, tests/pattern_crash_resume.rs). The 0.3.0/0.3.1 truth this bullet originally recorded — silence, no live producer for the typed mapping — was superseded when the upstream death-delivery unit landed; the deadline remains the wall only when nothing is there to die.
  • The receive quantum is hardcoded upstream (upstream ASK-2). The substrate’s 5-second IO quantum is not caller-settable and an elapsed quantum is distinguishable from a dead socket only by error text; this crate isolates that seam in one place, treats elapse as a benign re-arm, and every wait parameter it exposes is a pure wait quantum — an elapsed wait returns Ok(None)-shaped quiet, never a protocol outcome.
  • No backpressure vocabulary exists on the participant surface. A slow consumer surfaces nothing to anyone (F-0c §R5); this crate adds no parallel vocabulary and will inherit the substrate’s typed Accept/Defer/Reject home when the upstream wiring lands (F-3a R5).

Re-exports§

pub use action_dispatch::ActionDispatchError;
pub use action_dispatch::ActionDispatchOutcome;
pub use action_dispatch::conversation_for_action;
pub use action_dispatch::dispatch_action;
pub use anomaly::Anomaly;
pub use anomaly::AnomalyCounters;
pub use config::BusAttachment;
pub use envelope::Envelope;
pub use error::AttachError;
pub use error::CallError;
pub use error::CursorCommit;
pub use error::EnvelopeError;
pub use error::LeaveError;
pub use error::PublishError;
pub use error::RefusalClass;
pub use error::StoreError;
pub use handle::ConversationHandle;
pub use id::ConversationId;
pub use id::ConversationSeq;
pub use id::CorrelationId;
pub use id::MessageKind;
pub use id::ParticipantRef;
pub use id::PatternId;
pub use id::PublicationId;
pub use outcome::DepartReason;
pub use outcome::InboundRequest;
pub use outcome::IncomingRequest;
pub use outcome::JoinCredential;
pub use outcome::JoinGrant;
pub use outcome::LeaveOutcome;
pub use outcome::PublicationItem;
pub use outcome::PublishReceipt;
pub use outcome::RequestOutcome;
pub use outcome::SubscriptionItem;
pub use store::ResumeStore;

Modules§

action_dispatch
The ONE shared action-dispatch entry point (F-6a R3) — and the whole of F-6a’s sanctioned frame-conv edit.
anomaly
The handle’s typed anomaly surface and named counters (F-3a R2’s pinned home): every protocol anomaly is BOTH queued as a typed value the caller drains AND counted on a named, readable counter — never a log line wearing a type, never a silent drop.
config
Declared bus-attachment configuration. Every field is mandatory and caller-supplied — no Default implementation exists, so no policy value is ever assumed (the F-1a R4 discipline; the substrate’s own no-hidden-default stance for pool sizing).
envelope
The pattern envelope and its wire codec (design §2.1/§2.3).
error
Typed refusals and failures: the CONV_* slug family, envelope refusals, attach/publish/call errors, and cursor-commit outcomes.
handle
The transport-agnostic conversation handle (module root: declarations and re-exports only; logic lives in the named submodules).
id
Typed identity vocabulary: conversations, correlations, peers, sequences.
outcome
Typed pattern outcomes: request fates, inbound requests, subscription items, and the join/resume grants.
store
The caller-owned resume-state boundary, in frame vocabulary.
workflow
F-3b R2 — one workflow as one durable conversation.