Reference

Runtime integrity

Package Trax.StateMachine.PersistenceNamespace Trax.StateMachine.PersistenceSource SnapshotSelfCheck.cs, SnapshotMachineRegistry.cs, Machine.cs

Three checks that compare the C# machine a server runs with the TypeScript twin a client loaded, which may come from an older bundle: the schema-hash handshake, divergence detection on an advance, and the self-check that replays the committed corpus through the deployed engine. The differential tests prove the two agree at build time, from one commit; these run in production. All three are opt in from the client side: a client that sends nothing is not checked.

Members

MemberWhereValue
IMachine.SchemaHashC# serverlowercase-hex SHA-256 of ExportIr(); null for a machine whose IR export is refused by design, raw-delegate or declarative with a delegate guard, reducer or validator left in (no exportable IR, so no twin and no handshake)
TypedMachine.schemaHash / the twin's irHashTypeScript clientSHA-256 of the same committed IR, embedded in the generated twin
MemberReturnsMeaning
IMachine.Corpusstring?the machine's committed golden corpus, or null if it ships none
IMachine.SelfCheck()IReadOnlyList<string>replays Corpus through the machine's own engine; one diff per case it fails to reproduce (empty == agreement, and empty when there is no corpus)
SnapshotSelfCheck.Run(machines)IReadOnlyList<string>runs every machine's self-check and aggregates the diffs, machine-prefixed
IHealthChecksBuilder.AddTraxStateMachineSelfCheck(string name = "state-machines")IHealthChecksBuilderregisters SnapshotSelfCheck.Run over every discovered machine as an ASP.NET Core health check

Behavior

Schema-hash handshake

IMachine.SchemaHash and the twin's hash are taken over the same committed IR, so they are equal by construction (the drift tests pin ExportIr() to the committed ir.json, and the twin hashes that same file with its trailing newline stripped to match ExportIr()).

The client sends its schemaHash on each snapshot mutation (saveSnapshot, advanceSnapshot, loadSnapshot, sendSnapshot). When it differs from the server's registered machine, the request is refused with a SCHEMA_MISMATCH problem, so a stale client reloads instead of writing under an outdated contract. A client that sends no hash is not checked. That optional handshake belongs to the generic mutations only. A machine served through its own typed operations takes no schemaHash: its persisted documents carry the IR hash in their ids, and a node answers another version's id CLIENT_OUTDATED or SERVER_OUTDATED, so the check cannot be skipped by leaving a field out.

ISnapshotMachineRegistry.SchemaHash(machine) returns null for a machine with no exportable IR, and the check treats null as no check rather than throwing. The hash is computed once, on first read, and every concurrent reader waits for that value: a request that arrives while the first one is still building the machine gets the hash, never a null that would switch the check off.

Divergence detection

The schema hash catches a version mismatch; this catches a genuine behavioural disagreement on a real input. On advanceSnapshot, the client may send clientResult, the snapshot its twin computed for the advance, as canonical wire. The server re-drives the advance authoritatively and compares before it writes anything:

client twin: (pre-state, trigger, input) -> clientResult
server C#:   (pre-state, trigger, input) -> serverResult   <- authoritative

If the two canonical wires differ, the advance is refused with a CLIENT_DIVERGENCE problem and the client reloads. The refusal is real: the stored draft is exactly as it was before the request, so the reload shows the pre-state and a retry fires the trigger once. A client that sends no clientResult is not checked.

The comparison lives in ISnapshotDraftService.Advance(userKey, id, trigger, input, requestId, clientResult), which computes the advance, checks it, and only then writes. A custom ISnapshotDraftService that does not override that overload throws NotSupportedException when handed a client result, rather than persisting an advance it would then report as refused.

Startup self-check

The running server replays the same committed differential corpus the CI test replays, through the deployed C# engine.

The check is Healthy when every machine reproduces its corpus, and Unhealthy with every diff in its description otherwise. It replays each corpus in full on every call and does not observe the health-check cancellation token. Nothing runs it until it is registered, and registering it does not gate startup; a host that should refuse to start on a drifted engine calls SnapshotSelfCheck.Run(machines) from its own startup code.

A machine ships its corpus by overriding Corpus (for example from an embedded resource); a machine that ships none is skipped, not failed.

Both refusals surface on the mutation's problem field: SCHEMA_MISMATCH (save, advance, load, send) and CLIENT_DIVERGENCE (advance; nothing was written). See Result codes.

Examples

var registry = serviceProvider.GetRequiredService<ISnapshotMachineRegistry>();
string? hash = registry.SchemaHash("checkout");
builder.Services.AddHealthChecks().AddTraxStateMachineSelfCheck();

See also