Crate amberfork_model 

Canonical trajectory model for amberfork — the frozen contract every crate reads.

A Run is one agent trajectory: an ordered list of Steps plus optional DAG Edges. This is the input seam — amberfork-ingest produces it from OTel/plain JSON, and amberfork-align consumes it. It mirrors the public wire format documented in docs/trace-format.md; once this crate exists, these types are the source of truth and that document tracks them.

DiffResult is the matching output seam: what amberfork-align fills in and the CLI’s --json and the Leptos UI render.

Design rules baked into the types (see docs/design/design-run-diff-debugger.md):

• outcome is a run-level verdict supplied by the user, never inferred from span status.
• Timing (t_start/t_end) is display-only and is never an alignment signal, so it stays a raw string here rather than a parsed timestamp.
• inputs/outputs distinguish text from structured payloads in the type itself, because the diff engine text-diffs strings but field-diffs objects.

Structs

Attribution

Where the regression is attributed and how far it propagated.

Counterfactual

The counterfactual evidence behind an attribution.

DiffResult

The complete result of diffing two runs — the frozen output contract.

Edge

A directed DAG edge between step indices, [from, to] on the wire. A tuple struct so it serializes as a two-element array, matching docs/trace-format.md.

FieldDiff

A field-level difference within an aligned step pair (the object/text diff inside a sync move). Emitted only where the payloads actually differ.

Fork

The divergence point: the first non-sync block the alignment does not recover from (resync-k rule; see the 2026-07-08 amendment). Absent on a converged diff.

Meta

Envelope metadata for a result.

Move

One move in the alignment. The invariant tying kind to the indices — sync has both, log has only b_idx, model has only a_idx — is guaranteed by the Move::sync/Move::log /Move::model constructors.

Run

One agent trajectory: the unit amberfork diff aligns against another.

RunPair

The two runs a diff is over. a and b are neutral sides; which one failed is carried by each ref’s Outcome, and step indices in Move/Fork are relative to these.

RunRef

A lightweight handle to a run — enough to label a side in the UI without re-embedding the whole trajectory.

SchemaVersion

Version of the trace-format / model contract. Breaking changes (renames, removals, semantic shifts) bump it; additive optional fields do not. Kept as a newtype so the version is a first-class, self-documenting value across the workspace rather than a bare string.

Step

One node in a trajectory.

Warning

A non-fatal diagnostic emitted while building the diff (e.g. unmapped attributes, content absent from a metadata-only trace).

Enums

AttributionMode

Whether attribution was computed structurally or by counterfactual re-execution.

FieldDiffKind

How a single field changed between two aligned steps.

MoveKind

The class of an alignment move, in the process-mining sense the aligner uses: a synchronous move pairs a step from each run; a log/model move is a gap present on only one side. By convention run b is the “log” (observed/failing) and run a is the “model” (reference), so a MoveKind::Log step is extra in b and a MoveKind::Model step is missing from b.

Outcome

Run-level verdict, if known. Deliberately supplied by the user (an assertion, a label, a gold answer) — amberfork never derives it from trace/span status.

Payload

A step’s inputs or outputs. The variant is the semantic seam the diff engine reads: Payload::Text gets text diffing, Payload::Object gets field-level diffing. The untagged catch-all Payload::Other keeps the “any log massaged into this shape” promise alive — an array/number/bool payload is preserved verbatim instead of failing the parse.

Recovery

Outcome of counterfactual re-execution: did patching the origin step recover the run? The tri-state (rather than a bare bool) makes “we did not verify” a first-class, honest value.

Source

Which execution path produced the inputs: passively aligning existing traces, or an amberfork record capture session.

StepKind

The structural class of a step. Part of the identity the aligner keys on. This is the canonical, post-normalization vocabulary: amberfork-ingest is responsible for mapping the many framework-specific span kinds down onto these four.

WarningCode

Known warning codes. A closed set so the vocabulary stays single-sourced across crates; adding a code is a deliberate, versioned change to this contract.