Module trace 

RunTraceStore — the persisted per-Run trace rail (TraceEvent stream) plus the normalized worker-stats types (TokenUsage / WorkerStats) shared by the trace rail and the crate::store::run::StepEntry step-stats extension.

Two rails observe the same dispatch (issue: per-step run stats):

• crate::store::run::StepEntry — the terminal summary of one dispatched step (write-once, appended by the dispatcher after the outcome is known; carries duration / usage / model / verdict).
• TraceEvent (this module) — the in-flight stream of what is happening (core.step_dispatched, mw.long_hold_warn, …), append-only, per-Run, ordered by seq.

Everything here is purely observational: a failed append must never fail the dispatch it observes (callers warn-and-swallow — the same fail-open convention as EngineDispatcher::dispatch’s append_step_entry). The naming is deliberately Trace, not Log: in the Rust ecosystem “log” collides with the log/tracing facade crates, and this rail is domain data, not process logging.

Kinds are an open set of namespaced strings — writers may insert new kinds without a schema migration. Current namespaces:

• core.* — engine/dispatcher (run_started / step_dispatched / step_completed / cancel_requested / run_finished)
• mw.* — middleware (long_hold_warn, …)
• worker.* — adapter / worker self-reports
• ext.* — future external writers (Lua flow, enhance flow, tools)

Layering invariant (future mlua-swarm-trace crate split): this module must not depend on engine types — only crate::types ids and serde values.

Re-exports

pub use sqlite::SqliteRunTraceStore;

Modules

kind

Well-known TraceEvent.kind values written by the engine itself. The kind axis is an open set — these constants exist so in-tree writers and tests agree on spelling, not to constrain writers.

sqlite

SqliteRunTraceStore — SQLite-backed RunTraceStore using [rusqlite-isle], sharing the same database FILE as crate::store::run::SqliteRunStore (~/.mse/store/run.sqlite by default) in its own run_trace table. Sharing the file keeps “one Run’s persistence” a single artifact on disk; each store still owns its own confined Connection (its own AsyncIsle thread), so both connections set busy_timeout to ride out each other’s short write transactions.

Structs

InMemoryRunTraceStore

Process-volatile RunTraceStore — the default when no persistent backend is wired.

TokenUsage

Aggregated token usage for one worker attempt, normalized across worker kinds (agent-block agent.run return / subprocess declared mapping / operator self-report). Field names follow the Anthropic wire convention (input_tokens / output_tokens) that agent-block already normalizes OpenAI-style responses into.

TraceEvent

One persisted trace event — a member of a Run’s append-only stream.

TraceEventDraft

The caller-supplied half of a TraceEvent — the store assigns seq and ts_ms at append time.

TraceHandle

A cheap, cloneable write handle binding one run_id to a RunTraceStore — the single port through which the dispatcher, middlewares (via Engine::trace_handle), server handlers, and any future writer append trace events. Appends are best-effort: a store failure is logged at warn and swallowed, never propagated (fail-open, matching the append_step_entry convention).

TraceQuery

Filter/paging parameters for RunTraceStore::list. All filters AND together; latest and after are mutually exclusive with latest winning (it answers “show me the tail” regardless of any cursor the caller also carried).

WorkerStats

Normalized per-attempt worker statistics, reported by a worker boundary (spawner fold site / result captor / POST /v1/worker/submit) into the engine and folded into the terminal crate::store::run::StepEntry by the dispatcher.

Enums

TraceStoreError

Errors surfaced by a RunTraceStore implementation.

Constants

DEFAULT_TRACE_LIST_LIMIT

Default list page size when a query sets neither limit nor latest.

DEFAULT_TRACE_MAX_EVENTS_PER_RUN

Default per-Run retention ceiling — appends beyond this many events prune the oldest rows first.

TRACE_PAYLOAD_CAP_BYTES

Byte cap applied to TraceEvent::payload and WorkerStats::adapter_data before persisting. Oversized values are replaced by a truncation marker object (see cap_payload) — the trace rail is an observability artifact, not a blob store.

Traits

RunTraceStore

Persistence interface for the per-Run trace stream.

Functions

cap_payload

Replace an oversized payload with a truncation marker carrying the original size and a head excerpt, so a runaway writer cannot bloat the trace store. Values at or under TRACE_PAYLOAD_CAP_BYTES pass through unchanged.