ipc library

lazily-spec IPC wire types for Dart.

Exposes the language-agnostic lazily wire protocol (Snapshot, Delta, CrdtSync, DeltaOp, NodeState, IpcValue, IpcMessage, NodeKey, and the permission boundary), plus the lazily-lean transition helpers (cellSetOps, memoOps, signalOps, BatchFlush) that mirror the Lean 4 formal model, the distributed CRDT plane runtime (Hlc, StampFrontier, CrdtPlane, CrdtPlaneRuntime), causal receipts, the command / RPC message plane (command-plane-v1: CommandSubmit, CommandProjection, CommandRpcClient), and signaling.

See package:lazily/lazily.dart for the reactive family (Slot / Cell / Signal / StateMachine / StateChart / SourceMap / SourceTree / TextCrdt / SeqCrdt / SemTree).

Classes

ArrowBackend: Apache Arrow blob backend: holds spilled payloads as Arrow IPC stream bytes and resolves a descriptor to the buffer's raw bytes with no copy.
BatchFlush: lean BatchFlush + theorems batch_frontier_is_coalesced, batch_flush_advances_epoch_once, batch_flush_ops_are_frontier_invalidations.
BenchmarkResult: A single benchmark result.
BlobBackend: The adapter seam: a backend mints descriptors via write and resolves them zero-copy via readView.
BlobRouter: Receiver-side multi-backend resolver. Holds backends by BlobBackendKind and resolves any descriptor by its backend discriminator — a shm descriptor routes to the shm backend, an arrow descriptor to the arrow backend, etc. (the resolve_wrong_backend law: a descriptor never resolves against a backend of the wrong kind).
CallState: Resolution state of an RPC call.
CallStateConflict
CallStatePending
CallStateResolved
CausalReceipt: A single causal receipt.
CausalReceipts: The wire envelope for causal-receipts messages.
ClientAnswer
ClientIce
ClientJoin
ClientLeave
ClientMessage
ClientOffer
ClientRelay
Clock: Monotonic clock seam (spec § SyncDriver — policy injected, no runtime in core). The driver never schedules itself; the host calls SyncDriver.tick on its own cadence and supplies wall-free monotonic millis.
CommandApplyDuplicate
CommandApplyRecorded
CommandApplyStaleGeneration
CommandApplyStatus: The outcome of applying a frame to the projection reducer.
CommandApplyTerminalConflict
CommandApplyUnknown
CommandCancel: A cancel frame for a previously-submitted command.
CommandEvent: A single command progress event.
CommandEvents: A batch of command events.
CommandMessage: The externally-tagged command message envelope.
CommandMessageCancel
CommandMessageEvents
CommandMessageProjection
CommandMessageSubmit
CommandPolicy: Per-command behavior policy.
CommandProjection: The folded command projection reducer. Mirrors the Rust CommandProjection.
CommandProjectionEntry: One command's folded projection entry.
CommandProjectionImage: A whole projection image (a checkpoint / reconnect snapshot).
CommandRpcClient: RPC facade over the command plane. submit builds and sends CommandSubmit; incoming frames and receipts are folded via ingest*; a unary call resolves only when the projection reaches a terminal outcome — never on an ACK or an accepted event.
CommandSubmit: A submitted command frame.
CommandTransport: Transport used by CommandRpcClient to emit command-plane frames.
ConvergedEntry: The result of a converged node.
CrdtOp: One CRDT cell op on the wire (state-based / CvRDT).
CrdtPlane: The CRDT plane: an Hlc + a StampFrontier + the live membership set.
CrdtPlaneRuntime: A state-based CRDT plane runtime with anti-entropy.
CrdtSync: A CRDT anti-entropy sync frame (the multi-writer plane).
Delta: An incremental change set (protocol.md § Delta).
DeltaApplyStatus: The outcome of attempting to apply a Delta (lean ApplyDecision).
DeltaApplyStatusApply: The delta was sequential and may be applied; the new epoch is newEpoch.
DeltaApplyStatusResyncRequired: A gap, reorder, or sender restart was detected; request a fresh snapshot.
DeltaOp: One incremental operation in a Delta (protocol.md § DeltaOp variants).
DeltaOpCellSet: Changed-value cell write, PartialEq-guarded at the source.
DeltaOpEdgeAdd: New dependency edge.
DeltaOpEdgeRemove: Removed dependency edge.
DeltaOpInvalidate: Dirtied, not yet recomputed (lazy).
DeltaOpNodeAdd: New node (optional wire-stable key).
DeltaOpNodeRemove: Removed node (free-list reuse: Remove then Add).
DeltaOpSlotValue: A recompute published a new value.
DurableOutbox: Sender-side at-least-once outbox contract (spec § DurableOutbox).
EdgeSnapshot: A dependency edge: dependent reads dependency.
FileOutbox: Ready-to-use durable filesystem outbox.
FileOutboxStore: Append-only filesystem OutboxStore.
Hlc: A hybrid logical clock (Karger-Shrinkman-Levine).
HlcStamp: Runtime HLC stamp — a total order (wall_time, logical, peer).
InMemoryOutbox: In-memory DurableOutbox — correct within a process lifetime; the default.
InMemoryStore: Ordered process-local OutboxStore.
InProcessBackend: Default in-process backend: wraps ShmBlobArena for the single-address-space case (the FFI host ↔ a binding loaded in the same isolate).
IpcMessage: A length-prefixed, tagged Snapshot, Delta, CrdtSync, or reliable-sync control frame (ResyncRequest / OutboxAck) (protocol.md § IPC). The CrdtSync variant carries multi-writer plane traffic alongside the single-producer mirror; the control frames ride the same framed, tagged plane in reverse (receiver → sender) for reliable sync (#lzsync).
IpcMessageCrdtSync
IpcMessageDelta
IpcMessageOutboxAck
IpcMessageResyncRequest
IpcMessageSnapshot
IpcSink: Transport sink for IPC messages. send returns true on success; a false return is a transient send failure the driver retains-and-stalls on (it is never fatal). Mirrors the IpcSink trait in lazily-rs/src/ipc.rs.
IpcSource: Transport source for IPC messages. recv returns the next message, or null when the source is currently exhausted or closed. A read failure is signalled by throwing (the driver surfaces it as DriverError). Mirrors the IpcSource trait in lazily-rs/src/ipc.rs.
IpcValue: A DeltaOp cell payload (protocol.md § IpcValue).
IpcValueInline: Inline byte-array payload ({"Inline": [u8]}).
IpcValueSharedBlob: A payload descriptor into shared memory ({"SharedBlob": ShmBlobRef}).
NodeKey: A validated /-joined path addressing a keyed collection entry.
NodeSnapshot: A serialized node in a Snapshot (protocol.md § NodeSnapshot).
NodeState: The body of a NodeSnapshot / NodeAdd (protocol.md § NodeState).
NodeStateOpaque: A visible node whose value cannot be serialized (the bare "Opaque" unit).
NodeStatePayload: Concrete serialized value bytes ({"Payload": [u8]}).
NodeStateSharedBlob: A concrete value stored in shared memory ({"SharedBlob": ShmBlobRef}).
OrSet: An observed-remove set (OR-set) liveness cell.
OutboxAck: Reliable-sync reverse-channel control frame: prove receipt through throughEpoch (#lzsync, protocol.md § DurableOutbox).
OutboxStore: Dumb ordered byte storage for the durable outbox protocol.
PeerPermissions: Default-deny, per-peer allowlist of RemoteOp grants.
Progress: What one SyncDriver.tick accomplished (spec § SyncDriver).
ReceiptApplyStatus: The result of attempting to observe a receipt into a ReceiptProjection.
ReceiptDuplicate
ReceiptProjection: The monotonic ledger view: tracks the latest and terminal receipt per causation id.
ReceiptRecorded
ReceiptStaleGeneration
ReceiptTerminalConflict
RemoteOp: { kind: OpKind, node: NodeId }. A read grant never implies write or effect.
ResyncAction: Receiver decision for an inbound frame (spec § ResyncCoordinator).
ResyncActionApply: Apply the frame and advance the receiver epoch.
ResyncActionIgnore: Drop the frame (already-applied re-delivery, malformed, a duplicate request suppressed while resyncing, or a reverse-channel control frame arriving at a data receiver).
ResyncActionRequestSnapshot: A gap was detected; request a fresh Snapshot covering fromEpoch.
ResyncCoordinator: Receiver-side reliable-sync coordinator.
ResyncRequest: Reliable-sync reverse-channel control frame: request a covering Snapshot on a detected gap (#lzsync, protocol.md § ResyncCoordinator).
RoutedFrame
ServerAnswer
ServerError
ServerIce
ServerMessage
ServerOffer
ServerPeerJoined
ServerPeerLeft
ServerRelay
ServerWelcome
ShmBlobArena: An in-process blob arena. Manages blob storage with generation/epoch tracking and header validation.
ShmBlobRef: Descriptor into a shared-memory blob arena (protocol.md § Shared-memory IPC).
ShmBlobTransfer: A zero-copy cross-isolate blob transfer: a ShmBlobRef descriptor paired with its payload wrapped in TransferableTypedData. Sendable over a SendPort; the wrapped buffer crosses to the receiving isolate with no copy (a move). The receiver calls receive once to adopt the payload and re-validate it against the header. Dart's isolate-model realization of the shared-memory blob path (see ShmBlobArena).
SignalingRoom: A signaling room. Transport-agnostic — the caller drives receive / disconnect and delivers the emitted RoutedFrames over the transport.
Snapshot: Full graph state, sent on connect and on resync (protocol.md § Snapshot).
SnapshotProvider: Sender-side answer to a peer's IpcMessageResyncRequest (spec § SyncDriver).
SpillResult: The outcome of spilling: the (possibly rewritten) message and the total spilledBytes moved off the wire into backends.
StampFrontier: Per-peer stamp frontier: the highest HlcStamp observed from each peer.
StampFrontierEntry: A (peer, WireStamp) entry in the per-peer stamp frontier.
StateProjectionMirror: Tracks which slots are dirty and produces a coalesced flush Delta.
StoredOutbox<S extends OutboxStore>: Storage-independent durable outbox protocol.
SyncDriver: Full-duplex reliable-sync loop driver (spec § SyncDriver).
WireLwwRegister<V>: A last-writer-wins register liveness cell (per-pid alive, owner lease).
WireStamp: Wire mirror of the runtime HLC stamp — a total order (wall_time, logical, peer) (protocol.md § Distributed).

Enums

BlobBackendKind: Which pluggable blob backend resolves a ShmBlobRef descriptor (#lzzcpy, zero-copy transport).
CommandEventKind: The kind of a progress event. Terminal-flavored event kinds (cancelled/superseded/timed_out) do not themselves make a command terminal — only the terminal receipt does.
CommandStatus: The folded lifecycle status of a command.
DedupePolicy: How duplicate submits are deduplicated.
OpKind: The three independently-gated remote operation kinds.
ReceiptOutcome: The lifecycle outcome of a receipt.
SignalingErrorCode: Signaling error codes.
SignalingMode: Permission mode for a signaling room.

Functions

benchmark(String name, void body(), {int iterations = 10000}) → BenchmarkResult: Run a benchmark: execute body iterations times and measure the total.
buildStateEvent(String docHash, String type, Map<String, dynamic> fields, String eventSuffix) → Map<String, dynamic>: Build a state-backbone event for the agent-doc ledger.
cellSetOps(NodeId node, IpcValue oldValue, IpcValue newValue) → List<DeltaOp>: lean cellSetOps + theorem equal_cell_set_is_silent / changed_cell_set_emits_cell_set: the PartialEq cell guard. An equal write emits no op; a changed write emits exactly one DeltaOpCellSet.
documentHash(String path) → BigInt: Compute the FNV-1a 64-bit document hash for a file path or string.
downstreamInvalidations(List<NodeId> downstream) → List<DeltaOp>: lean downstreamInvalidations: each downstream node becomes an DeltaOpInvalidate, preserving order.
memoOps(NodeId node, IpcValue oldValue, IpcValue newValue, List<NodeId> downstream) → List<DeltaOp>: lean memoOps + theorem equal_memo_suppresses_downstream / changed_memo_publishes_then_invalidates: memo equality suppression. An equal recompute is silent; a changed recompute publishes a DeltaOpSlotValue then invalidates the downstream frontier.
resolveValue(IpcValue value, BlobBackend backend) → BlobView?: Resolve an IpcValue against a single backend: inline bytes returned directly, IpcValueSharedBlob resolved zero-copy. Returns null if a SharedBlob fails to resolve (unknown / stale / corrupt).
runBenchmarkSuite({int iterations = 10000}) → List<BenchmarkResult>: Run the full benchmark suite. Returns all results.
signalOps(NodeId node, IpcValue oldValue, IpcValue newValue) → List<DeltaOp>: lean signalOps + theorem equal_signal_is_silent / changed_signal_materializes_slot_value / signal_never_emits_bare_invalidate: a changed eager Signal materializes a concrete DeltaOpSlotValue for its backing slot — never a bare DeltaOpInvalidate.
spillMessage(IpcMessage message, BlobBackend backend, int threshold) → SpillResult: Spill large payloads across an IpcMessage's value/state sites: Snapshot node states, Delta CellSet/SlotValue payloads + NodeAdd states, and CrdtSync op states. Returns a SpillResult with the rewritten message and the total bytes spilled.
spillValue(IpcValue value, BlobBackend backend, int threshold) → (IpcValue, int): If value is an IpcValueInline of >= threshold bytes, write it to backend and return a IpcValueSharedBlob descriptor; otherwise return value unchanged. The second field is the number of bytes spilled (0 if not spilled).
validateBlobRef(ShmBlobRef ref, {int? maxLen}) → bool: Validate a ShmBlobRef descriptor against expected bounds.

Typedefs

BlobView = Uint8List?: A zero-copy view into a backend's resolved bytes.
Epoch = int
NodeId = int: Wire-stable node and peer identifiers (protocol.md § Shared Types).
OutboxFrame = (Epoch, IpcMessage): One retained outbox frame: its epoch retention key and the message.
PeerId = int
StoredOutboxFrame = (Epoch, Uint8List): One serialized outbox frame returned by OutboxStore.scanAfter.

Exceptions / Errors

DriverError: A transport error surfaced by SyncDriver.tick.
PermissionDenied: Thrown by PeerPermissions.check when peer lacks op.