Reference

Decision replay and state hash rules

Source IDecisionObserver.cs, QuestionFingerprint.cs, StateDigest.cs, StateHashKey.cs

Trax.Core reports every answered question and every routing to an IDecisionObserver, and asks an IDecisionReplay for an earlier answer before it asks a decider. Both are in Trax.Core.Decisions, both are optional, and both are found in the train's Memory, then the container. Decisions explains why replay works this way; Trax.Effect's implementation is in Decision Recording and Models.

IDecisionObserver

public interface IDecisionObserver
{
    bool Required => false;
    Task Decided(DecisionMade decision, CancellationToken cancellationToken);
    Task Routed(TrackRouted routing, CancellationToken cancellationToken);
    Task Refused(DecisionRefused refusal, CancellationToken cancellationToken) => Task.CompletedTask;
}

An observer that cannot be resolved at all fails the step either way. An observer that cannot record a refusal is logged, and never replaces the refusal as the reason the step failed, even when it is Required.

DecisionMade

StateType and QuestionType let a host treat a decision by what it was about, matching with inheritance, where a key would match only one name.

DecisionRefused

Train, RunId, Question, Occurrence, Fingerprint, Answer (null when there was none), Decider, Reason and QuestionType.

TrackRouted

Train, RunId, On (the enum or marker type routed on), Track (the track's name), and FallbackReason, set when the decision was not followed and a fallback track ran.

IDecisionReplay

public interface IDecisionReplay
{
    Task<RecordedAnswer?> Replay(
        string train, string runId, string key, int occurrence, CancellationToken cancellationToken);
}
 
public sealed record RecordedAnswer(Answer Answer, string Fingerprint)
{
    public string? StateHash { get; init; }
}

Replay is asked on the run's path, once per question, by the same coordinates DecisionMade carries. It returns null to ask the decider. A host that replays stores each DecisionMade.Answer with its Fingerprint and StateHash and hands them back exactly as stored. Whatever Replay throws fails the step, classified as the exception says, because a replay that cannot be read cannot be told from a run with nothing to replay. A question whose answer is replayed is not put to the shadows.

Fingerprint

A SHA-256 over one asking of a question as the chain declares it: the step, the state's type, the kind of question, its key, its words, and every option or level with its description (or what yes and no mean). It never covers the state's value.

Replay checks

A replayed answer is checked before it is acted on. The decider is asked afresh when:

DecisionMade.ReplayRefused says which check refused the answer, and never quotes the recorded answer. A recorded choice of a member the switch has no track for is replayed like any other and takes the Otherwise track again.

When the state hash key is the cause, ReplayRefused names it: an answer recorded under a key while this run hashes without one, or the reverse, says so; a keyed hash that differs says the state changed "or the state hash key has changed since"; and a key that cannot be resolved is reported as that, not as a change in the state.

State hash

Taken only when needed: to check a replayed answer that passed its fingerprint and fit checks, or before the decider is asked when a decision observer is registered, so the hash an observer records is of the state the decider was given.

A keyed and an unkeyed hash never match.

What it covers

• Every instance field of the state's runtime type, public or not, and every value they hold, recursively: auto-properties, tuple items, record members, and the members of a derived type held where a base type or an interface is declared.
• Each value's runtime type, named with its assembly, and its fields base type first and by name.
• Every element of an array, inline array or fixed buffer, and each array dimension's length and lower bound.
• A framework collection as its elements and its comparers. A wrapper (a read-only wrapper, a Collection<T> and so a keyed or observable collection, a view of a dictionary's keys) as what it wraps, with its own comparers, so a key view is written as its whole dictionary and a list of the state's own type by its fields.
• A set, dictionary or bag with its elements sorted, so equal contents hash alike whatever order they were added in.
• An enum with its underlying type and its members' names and values; a local DateTime with its daylight-saving flag.

It covers the state's value and nothing else: what a decider reads from elsewhere is not in it. Only the hash leaves the run, never the state.

States with no hash

StateHash is null, and the state never replays, when the state:

• holds a reference cycle
• is nested deeper than 64 levels, or its encoding passes 1,000,000 values or 16 MiB
• holds a delegate (an ORM's lazy-loading proxy, for instance), a pointer or native handle
• holds a Type, a MemberInfo or an Assembly
• holds a stream, a wait handle, a task or a thread
• holds a non-generic Hashtable or SortedList, a BlockingCollection<T>, a wrapper ArrayList makes (ArrayList.Adapter, ReadOnly, Synchronized...), or a collection that enumerates by its own code
• holds a CultureInfo other than the framework's shared instance (CultureInfo.GetCultureInfo(name) or InvariantCulture); CurrentCulture and new CultureInfo(...) give no hash
• has a field that throws when read, or a collection that throws when enumerated

It is also null when the container's StateHashKey cannot be resolved.

StateHashKey

using Trax.Core.Decisions;
 
var stateHashKeyBytes = Convert.FromBase64String(configuration["StateHashKey"]!);
 
services.AddSingleton(new StateHashKey(stateHashKeyBytes));   // at least 32 bytes

Trax.Core reads the key from the train's container. Hashes are compared exactly, so every process that may repeat a run uses the same key, and adding or changing the key means each answer recorded before it is asked afresh once. Trax.Effect's AddDecisionRecording can supply the key from its options or from configuration.

SDK Reference

Decide | Switch | AddDecisionRecording