Expand description
A shared vocabulary for what two turn paths disagreed about.
§Why a type and not a report format
Classifying divergences is where the value of a shadow stage is. An adopter
who runs TurnPlanner beside their existing
tool loop ends up with two descriptions of the same turn and a pile of
differences, and what they need next is a name for each kind of difference
— the same name the next adopter uses, and the same name the next release
uses, so a report can be read across both.
Each side describes its turn as a TurnSummary. The Turnframe side gets
one for free from PlannedTurn::summary;
the authoritative side is filled in by the adopter from their own logs, and
the fields are deliberately shallow enough that a free tool-calling agent
can be described in them.
§The asymmetry, in the type
Not every difference is a regression, and a comparison that cannot say so will be read as though it were. This module states the case that matters: when this library refuses a mutation because the target was ambiguous and the previous path performed it anyway, the finding is against the previous path. It picked one of several records the user might have meant, and being right most of the time is not the same as being correct.
So that case is its own variant —
Divergence::RefusedUnresolvedTargetThatRan — carrying
Attribution::Authoritative, and it is subtracted from the plain
Divergence::Mutations difference rather than counted twice. Every other
finding carries the attribution the comparison can actually justify, which
is usually Attribution::Undetermined: a difference a human still has to
judge is reported as one.
Structs§
- ActSummary
- One act a side extracted from the turn.
- Clarification
Summary - One question a side asked before doing anything.
- Divergence
Report - Everything two summaries of one turn disagreed about.
- Finding
- A divergence together with the side it counts against.
- Mutation
Summary - One mutation a side would run.
- Refused
Mutation - A mutation a side understood and did not perform.
- Turn
Summary - One side’s account of a turn.
Enums§
- Attribution
- Which path a finding is against.
- Divergence
- One way two paths disagreed about the same turn.
- Refusal
Reason - Why a side did not run a mutation it had understood.
- Side
- Which of the two paths a summary or a finding is about.
Functions§
- compare
- Compares the two sides of one turn.