SsalKit.StableHashing 0.0.6

← SsalKit

English | 한국어 | 日本語

SsalKit.StableHashing

Platform- and process-independent 64-bit checksums via a version-locked canonical encoding contract: [StableHashContract]/[StableHashMember] drive a source generator that writes ComputeStableHash() for you, hashed with an internally ported XxHash64. Zero dependencies.

Why SsalKit.StableHashing?

object.GetHashCode() looks like it does this job, but the BCL is explicit that it does not: its documented contract permits the value to differ between runs of the same program, between processes, and across .NET versions, and warns against ever persisting it or relying on it staying the same anywhere outside the lifetime of one object. That rules out exactly the use cases where you actually want a "hash of this object" — a checksum saved to a database, sent over a network, compared between two machines, or compared between a run today and a run next month.

System.IO.Hashing (the BCL's own XxHash64, XxHash3, etc.) does not fill that gap either — on purpose. It hashes bytes you already have; it has no opinion about how to turn a C# object into those bytes in a way that stays consistent forever. That "how to turn an object into bytes" decision — field order, numeric width, string encoding, what happens to -0.0 or 1.0m vs 1.00m — is exactly the part that has to be nailed down and never changed again, or every previously computed hash silently goes stale. That's the actual product here: a canonical encoding contract, not a hash algorithm. The hash algorithm is comparatively replaceable; the encoding rules are not.

SsalKit.StableHashing:

• [StableHashContract] / [StableHashMember(id)] mark a type and its members. A source generator bundled in the package writes a ComputeStableHash() extension method for you at compile time — no reflection, AOT- and trimming-safe.
• The encoding is a permanently fixed v1 contract (byte order, field widths, string encoding, nested-contract recursion — see below), so a hash computed today and a hash computed by a future patch of this library, on a different machine or architecture, are the same value for the same logical input, forever.
• Equality-consistent by construction. decimal, DateTimeOffset, and float/double each have a trap where == is true but the underlying bits differ; the encoding normalizes all three so that a == b always implies encode(a) == encode(b) (see Equality-consistency invariant, below).
• Zero dependencies. The hash algorithm (XxHash64) is ported internally rather than pulled in from System.IO.Hashing, so the package stays BCL-only.

Typical uses: detecting when two lockstep/replay simulations have desynced (compare a per-tick hash instead of the whole state), skipping a redundant snapshot save when nothing actually changed, deterministic A/B bucketing (hash % 100), and deriving a reproducible, named random stream: StableHash64.Value can be handed straight to new SsalKit.Randomness.DeterministicRandom(hash.Value) (from the separate, optional SsalKit.Randomness package) to turn any hashable value into a seed. The two packages have no dependency on each other — this is a documented usage pattern, not a coupling.

Installation

dotnet add package SsalKit.StableHashing

The package contains both the runtime types (StableHash64, StableHashWriter, the two attributes) and the source generator — no separate analyzer package to install, and no PackageReference of its own.

Quick Start

using SsalKit.StableHashing;

[StableHashContract("game.player-snapshot", Version = 1)]
public sealed record PlayerSnapshot
{
    [StableHashMember(1)] public string PlayerId { get; init; } = "";

    [StableHashMember(2)] public int Level { get; init; }

    [StableHashMember(3)] public long Gold { get; init; }
}

var snapshotA = new PlayerSnapshot { PlayerId = "player-42", Level = 17, Gold = 2_450 };
var snapshotB = new PlayerSnapshot { PlayerId = "player-42", Level = 17, Gold = 2_450 };

StableHash64 hashA = snapshotA.ComputeStableHash();
StableHash64 hashB = snapshotB.ComputeStableHash();

hashA == hashB;      // true -- two separate instances, same member values
hashA.ToString();     // "9c3f38517dbc66aa" -- lowercase, 16-char hex
hashA.Value;          // the raw ulong

[StableHashMember] is opt-in: a member without it is simply excluded from the contract, no diagnostic. Members are encoded in ascending Id order, not declaration order, so reordering or renaming members in source never changes the hash — only changing a member's Id, or the type of value it holds, does.

API Overview

Encoding contract (v1)

This encoding is a permanent, versioned contract. Every rule below — byte order, field widths, the floating-point/decimal normalization rules, the leading format marker — is fixed forever. Changing any of it would silently change every hash this library has ever produced, corrupting every consumer's stored checksums. If the encoding ever needs to evolve, it ships as a new, separate API (e.g. a hypothetical StableHash128/StableHashWriterV2), never by changing this one's behavior.

Every produced stream starts with a single format-marker byte (0x01), then the contract header: the contract name (as a length-prefixed string, below) followed by its Version as a little-endian int32. A member's value is preceded by its member id (little-endian int32). All fixed-width integers are little-endian.

v1 rejects the following, as a compile-time diagnostic rather than a runtime surprise: DateTime (SSALH003 — use DateTimeOffset or DateOnly), Dictionary/HashSet/any other unordered or arbitrary IEnumerable<T> (enumeration order isn't guaranteed), object, delegates, pointers, interfaces and abstract types (the runtime type isn't known at compile time), a user-defined type with no [StableHashContract], a circular contract graph, and a generic contract type.

Equality-consistency invariant

For every supported type, a == b implies encode(a) == encode(b).

Three BCL types have a trap where this would otherwise silently break — two values that compare equal, but whose underlying bits differ — so the encoding normalizes each one before writing it:

Two more totality rules fall out of the same principle:

• string: malformed UTF-16 (an unpaired surrogate) uses Encoding.UTF8's default replacement-character (U+FFFD) fallback, which is itself deterministic — there is no input that fails to encode.
• ImmutableArray<T>: default(ImmutableArray<T>) (uninitialized) is treated as empty, matching how most code already treats the two interchangeably, and keeping the writer a total function over every value of the type.

The invariant only runs one direction: encode(a) == encode(b) does not imply a == b — see Hash semantics, below.

Diagnostics

Every error above suppresses generation for that contract type entirely — there is no partial generation. A warning never blocks generation.

Hash semantics

StableHash64 is a 64-bit fingerprint, and every fixed-width hash gives you the same asymmetric guarantee, not a symmetric one:

• If two hashes differ, the underlying values are certainly different (100%). This falls straight out of encode/hash being deterministic functions: equal inputs cannot possibly land on different outputs.
• If two hashes are equal, the underlying values are almost certainly the same — but not guaranteed. With a 64-bit output space, the birthday bound puts the point where collisions become likely at around 2^32 (~4.3 billion) distinct hashed values. For comparing a handful of values — two simulation states, a snapshot against its predecessor, a cache key — the odds of an accidental collision are astronomically small. They are not zero.

StableHash64 is therefore not suitable as the final word on identity where a collision would be catastrophic — deduplication that silently discards data on a false match, for instance. It's the right tool for cheap, fast comparison (desync detection, change detection, cache/ETag material, deterministic bucketing) where an essentially-never event causing a false positive is an acceptable, or independently-checked, risk.

Security

StableHash64 is not a cryptographic hash. There is no collision-resistance guarantee against an adversary who deliberately constructs two different inputs that hash identically, no keying, and no protection against tampering. Do not use it for integrity checks against a malicious modifier, message authentication, password storage, digital signatures, or any other security-sensitive purpose — use System.Security.Cryptography.SHA256 or similar for those.

Performance

SsalKit.StableHashing is built around one performance contract: zero bytes allocated per ComputeStableHash() call. StableHashWriter is a ref struct that streams every value straight into the hasher's state (batched through a small inline staging buffer) — there is no intermediate byte[] serialization buffer, on any code path, including the string-encoding fallback for inputs too large for its stack buffer (which rents from ArrayPool<byte> instead of allocating).

Measured with BenchmarkDotNet v0.15.8, .NET 10.0.10, AMD Ryzen 9 3950X, Windows 11 (SsalKit.StableHashing 0.0.4). Numbers vary by hardware; reproduce them with the benchmark project. Allocated is 0 B in every row except the naive baseline.

Read the last two rows together, honestly: the naive approach — manually serializing a value into a byte[] and hashing that buffer — comes out faster in raw time (242 ns vs. 370 ns) than the generated streaming code. What it costs is 632 bytes allocated on every single call, where the generated path allocates nothing. That's a deliberate trade, not an oversight: on a tick loop, a save path, or any other hot path invoked thousands of times a second, zero GC pressure per call is worth more than a ~130 ns difference — the naive version's 632 B/call adds up to real collection pauses at scale, while the streaming design's cost stays flat regardless of call frequency. If ComputeStableHash() runs rarely (once per HTTP request, say), the raw-speed edge of hand-rolled serialization may matter less than never having to think about its allocation cost in the first place — which is what the generated path buys you either way.

License

MIT — see LICENSE.

AI disclosure: This project was built with AI assistance (Claude).