Crate salvor_core

Expand description

Salvor core: the stable public surface for the event model, replay engine, and deterministic context of durable agent runs.

A run is an append-only sequence of events; nothing else is state. On resume, completed model and tool calls are read from the log, never re-executed, and execution continues live from the first unrecorded step.

§What lives where

The types themselves live in salvor_replay, a pure, IO-free crate that also builds for wasm32-unknown-unknown so the v0.3 browser inspector can fold event logs client-side. That crate holds the event vocabulary (Event, EventEnvelope, RunId, SequenceNumber, SCHEMA_VERSION), the replay cursor (ReplayCursor and its typed Outcome permits), the state fold (derive_state into RunState), the values read back out of a log (ParkReason, RunSummary), the budget declaration and its crossing check (Budgets, Pricing, BudgetObservations, budget_observations), and the event renderers (event_kind, event_detail).

salvor-core re-exports that surface unchanged. Every salvor_core:: path that existed before the extraction keeps resolving, so the store, the runtime, the tools layer, and the CLI compile against the same names they always used. New code may depend on either crate; the names are identical. The split exists so the runtime and the browser inspector fold events with literally the same code, without the runtime’s IO edge leaking into the pure path.

Structs§

BeginPermit: Live permission to start a fresh run.
Budget: A budget limit: which dimension, and the ceiling set for it.
BudgetExtensions: The accumulated budget extensions granted by recorded resume inputs. See the module docs for the JSON shape they are parsed from.
BudgetObservations: The replay-derived quantities a budget check consumes. The loop builds one of these at each iteration start, exclusively from recorded data.
Budgets: The limits an agent declares. Every dimension is optional; an absent dimension is never checked.
DedupOrigin: Where a deduplicated tool call took its recorded output from: the run and the log position of the completion that already committed this call’s effect.
Emitted: An event the cursor produced in live mode, with the log position it must occupy.
EventEnvelope: One record in a run’s append-only log.
ForkOrigin: The recorded link from a forked run back to the run it forked from.
GraphBeginPermit: Live permission to start a fresh graph run.
LogValidator: A growing, always-well-formed log you fold candidates into one at a time.
ModelCallPermit: Live permission to execute a model call.
ModelReply: A replayed or freshly executed model call result.
NowPermit: Live permission to observe the clock.
Parked: A run parked awaiting resume input that has not arrived.
Pricing: Per-token pricing, in US dollars per million tokens. Required by the agent builder whenever a cost budget is declared.
RandomPermit: Live permission to draw random bits.
ReplayCursor: The pure replay/live cursor over one run’s event log.
RunId: Identifies a single run.
RunState: Everything a log prefix implies about a run.
RunSummary: A one-line-per-run projection of the log, returned by EventStore::list_runs.
SequenceNumber: A monotonic position within a run’s event log.
TokenTotals: Token usage accumulated across every completed model call in a log.
TokenUsage: Token counts reported for a model call.
ToolCallPermit: Live permission to execute a tool call.
UnresolvedWrite: The outstanding write an abandonment left unsettled.

Enums§

BudgetKind: Which declared budget dimension a run can bump against.
Effect: How a tool call may be retried and how it behaves on replay.
Event: Everything that can happen in a run.
LoggedStep: What the log holds at a divergence position.
Outcome: How the cursor answered a request: from recorded history, or with a permission to execute live.
ParkReason: Why a run parked instead of completing.
PendingCall: A recorded call intent with no recorded completion.
Performer: Who performed a tool call: the trust distinction a reader of the log needs to tell “salvor witnessed this” apart from “the client says this happened”.
ReplayError: Why replay could not continue.
RequestedStep: What orchestration produced at a divergence position.
RunStatus: Where a run stands, as derived from its log alone.
ValidationError: Why a candidate envelope is not the legal next event for a log.

Constants§

SCHEMA_VERSION: The schema version stamped onto every serialized event.

Functions§

budget_extensions: Folds a recorded log into the extensions a budget check has been granted.
budget_observations: Folds a recorded log into the observations a budget check consumes.
derive_state: Folds an event log into the RunState it implies.
event_detail: The informative payload of one event, rendered as a single line. Picks the fields that matter per kind: a tool call shows its name, effect, and (when a client performed it) that fact, a model completion its token usage, a suspension its reason. Hashes are shortened and every payload is truncated, so no full input, output, or error text reaches the progress stream; salvor history --json is the escape hatch for the untruncated envelope.
event_kind: The stable kind label for one event, matching the enum variant name so it reads the same as the wire form’s kind tag.
validate_extension_input: Validates a resume input against the budget-extension shape documented at module level. Applied by Runtime::resume when the run parked on a budget crossing, before the input is recorded.
validate_next: Decides whether candidate is the one legal next event to append to log.