Module executor 

Applying, replaying, and dispatching actions.

Three entry points, one commit discipline: apply_local runs an action on the local replica, minting a fresh envelope (the origin); replay decodes an envelope’s action and applies it, reproducing the identical change on any replica at the same base state (peers); dispatch is the locus-aware front door — ClientLocal applies and hands to the transport for replication; ServerPreferred submits to an authoritative host and fails closed when none answers.

The commit discipline is what makes replay deterministic: every apply pins the Automerge actor id (from the envelope’s ActionId) and the commit time, then restores the doc’s previous actor. A fresh actor id per action means its single change is seq == 1 on every replica, so the change hash is content-addressed identical everywhere.

Structs

CompensatingScope

The undo or redo of the steps marks (their change hashes) applying its compensating action on this thread: an outside consequence the action queues reads them (await_compensation), and the step counts as taken back (or brought back) only once that consequence settles (settle_compensation).

EntryReader

The entries of a document’s changes read in causal order, each continuation folded into its gesture’s first entry as it is read.

LocalTransport

A transport that only replicates locally (no host); records every replicated envelope for a caller/test to inspect. The default the toolkit installs when a session has no peer/host wiring yet.

Enums

Dispatched

What dispatch did with an action.

HostDecision

A host’s answer to a ServerPreferred submission.

Verified

What replaying a received change showed.

Constants

UNDONE_KEY

The document key prefix of a step’s undo marker, followed by the step’s change hash: true once taken back, a negative attempt count while its undo waits for an outside consequence to settle, a positive one while its redo does.

Traits

ActionTransport

The transport an action is handed to after (or instead of) local execution — the seam between the pure action model and whatever moves bytes (in-process broker, compositor socket, Iroh). The model never imports a transport, only calls this trait.

Functions

apply_local

Apply action to the local replica and return its replayable envelope. encoded is the serialized form carried to peers — must encode the same action.

apply_local_by

apply_local, attributing the resulting change to actor: the Automerge change commits under their actor so the room’s history names them the way it names a typing person. None keeps the ActionId-derived actor, as before.

apply_local_with_context

apply_local, with semantic provenance embedded in the resulting durable change. Use this at framework/action-door boundaries where the resource and human action label are already known.

await_compensation

The steps an outside consequence queued now settles, recording that their undo or redo waits for it; empty outside a compensation.

await_settlement

Mark the step hash as waiting for the outside consequence its undo (or, with redo, its redo) queued: the next attempt’s marker, negative for an undo, positive for a redo. The step stays as it was until settle_compensation completes it.

current_step

The undo step open on this thread, if any (see open_step).

dispatch

The locus-aware front door, routing action per its ExecutionLocus: ClientLocal → apply_local then transport.replicate; ServerPreferred → transport.submit_to_host, refusing when no authoritative host is reachable. The envelope’s id/timestamp are fixed before submission.

dispatch_by

dispatch, attributing the resulting change to actor — the executor owns the commit boundary, so it’s the only place that chooses which actor a change commits under, rather than each app remembering.

dispatch_by_with_context

Attributed variant of dispatch_with_context.

dispatch_with_context

dispatch, carrying semantic provenance into the replicated envelope and the committed CRDT change.

entry_message

The message context is written with by actor on doc: as the continuation of the actor’s previous entry when the change continues its gesture (a head of doc is the actor’s, of the same gesture and step), else whole. A function of the document, so a replaying device writes the same message, hence the same change.

entry_of

The entry of the change hash: its message’s, or for a continuation its gesture’s first entry with the continuation’s action (found by following its writer’s earlier changes).

inverse_as

The action’s inverse_encoded at doc, as the change written by actor records it: what the action mints depends on its writer.

invoking_context

The context of the action whose Action::apply is running on this thread: who invoked it and in which work group (an agent run). Pinned by the envelope like the actor and the time, so a replica replaying the action reads the same value. None outside an apply, or for an action dispatched with no context.

open_step

Open the undo step the changes committed on this thread join until the next one opens: every action applied meanwhile records it as its gesture, so the document’s history takes them back as one step. The host’s history opens one at every step boundary; None closes it.

recorded_form

The action as its change records it: itself when it fits the history budget, else with its large parts kept as content (EncodedAction::with_content_parts). An action too large even then is refused: a change never commits without the action it ran.

replay

Replay an envelope received from a peer: decode its action via registry and apply under the envelope’s pinned actor + timestamp. Applied at the envelope’s base_heads, this reproduces the identical document.

settle_compensation

Mark the undo (or redo) of the step hash complete: its outside consequence settled.

verified_compensation

Decode a recorded inverse only after reproducing its original change. Descriptive CRDT metadata alone cannot install executable history.

verify_change

Replay the action the change hash records on the document it was authored against, and check that it produces exactly that change: same operations, same actor, time and message, so the same hash. This is what a device that has the app does with every change it receives, beside the relay’s grant check: an author granted an action who wrote something else inside its storage units is caught here.