From 75ebc727f28fe9f2ed229553f1e409afc2621fdc Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 19 May 2026 18:35:16 +0100 Subject: [PATCH] Add CultNet simulation witness consensus --- .../cultnet-distributed-database/summary.md | 2 + .../Contracts/cultnet-distributed-database.md | 18 +- .../CultNetSimulationConsensus.cs | 293 ++++++++++++++++++ src/GameCult.Networking/README.md | 7 + .../NetworkingTests.cs | 113 +++++++ 5 files changed, 430 insertions(+), 3 deletions(-) create mode 100644 src/GameCult.Networking/CultNetSimulationConsensus.cs diff --git a/research/cultnet-distributed-database/summary.md b/research/cultnet-distributed-database/summary.md index 82caa713..893ab3c3 100644 --- a/research/cultnet-distributed-database/summary.md +++ b/research/cultnet-distributed-database/summary.md @@ -173,6 +173,7 @@ Shard catalog exchange now exists: implementation - client authority scopes for predicted local input documents - predicted/reconciled change events for client-side prediction +- simulation witness observations and deterministic consensus candidates ## Next Cut @@ -183,6 +184,7 @@ Build durable authoritative mutation logs: - return explicit resync-required responses when requested history is gone - then add simulation-frame rollback and resimulation helpers on top of predicted input streams +- add observation gossip once the local witness model has earned its shape That is the next foundation needed before membership, Raft-style failover, or CRDT policy work can be honest. diff --git a/src/GameCult.Networking/Contracts/cultnet-distributed-database.md b/src/GameCult.Networking/Contracts/cultnet-distributed-database.md index 41594a2a..c566467a 100644 --- a/src/GameCult.Networking/Contracts/cultnet-distributed-database.md +++ b/src/GameCult.Networking/Contracts/cultnet-distributed-database.md @@ -61,6 +61,8 @@ Implemented: implementation - client-authority scopes for locally predicted input documents - predicted and reconciled database change kinds for client-side prediction +- simulation witness observations for mesh-side opinions about frame facts +- deterministic consensus candidates derived from witness observations Not implemented yet: @@ -68,6 +70,7 @@ Not implemented yet: - leader election or automatic shard failover - durable log persistence and compaction - snapshot fallback for compacted log history +- transport messages/documents for witness observation gossip - rollback/resimulation helpers for simulation frames - declared CRDT merge policies @@ -87,6 +90,11 @@ Not implemented yet: - Predicted input state is not authoritative shared state. The shard log still decides the committed ordering and emits reconciliation when it corrects or confirms local prediction. +- Witness observations are immutable reports about a shard epoch, frame, + subject, claim kind, and claim hash. +- Consensus candidates are derived from observations. They may inform the + authoritative commit path, but they are not themselves committed world state + until a shard owner writes them into the log. ## Next Coherent Slice @@ -97,10 +105,14 @@ Add durable mutation-log storage and snapshot fallback: - return `ResyncRequired` when a replica asks for compacted history - after that, add simulation-frame rollback/resimulation helpers around predicted input streams +- add schema-v0 observation gossip once the local consensus document shape is + stable The log is wire-readable, replicas can apply it explicitly, a pull loop can drive non-primary shards from primary endpoints, and replica cursors can survive restart. Client-owned input documents can now be predicted locally and -reconciled when the authoritative log arrives. The next useful layer is making -authoritative mutation logs durable and compaction-aware. Membership and leader -election should wait until basic replica catch-up is boring. +reconciled when the authoritative log arrives. Nodes can also aggregate witness +observations into deterministic consensus candidates for simulation facts like +"who shot first." The next useful layer is making authoritative mutation logs +durable and compaction-aware. Membership and leader election should wait until +basic replica catch-up is boring. diff --git a/src/GameCult.Networking/CultNetSimulationConsensus.cs b/src/GameCult.Networking/CultNetSimulationConsensus.cs new file mode 100644 index 00000000..96407581 --- /dev/null +++ b/src/GameCult.Networking/CultNetSimulationConsensus.cs @@ -0,0 +1,293 @@ +using System; +using System.Collections.Generic; +using System.Linq; +using System.Security.Cryptography; +using System.Text; +using MessagePack; + +namespace GameCult.Networking +{ + /// + /// One witness report about a deterministic simulation fact. + /// + [MessagePackObject] + public sealed class CultNetSimulationObservation + { + /// + /// Gets or sets the observing runtime id. + /// + [Key("witnessRuntimeId")] public string WitnessRuntimeId { get; set; } = string.Empty; + /// + /// Gets or sets the shard id containing the observed simulation. + /// + [Key("shardId")] public string ShardId { get; set; } = string.Empty; + /// + /// Gets or sets the shard epoch observed by the witness. + /// + [Key("shardEpoch")] public long ShardEpoch { get; set; } + /// + /// Gets or sets the simulation frame or tick. + /// + [Key("frame")] public long Frame { get; set; } + /// + /// Gets or sets the subject this observation is about. + /// + [Key("subjectId")] public string SubjectId { get; set; } = string.Empty; + /// + /// Gets or sets the kind of claim, such as hit, input, collision, or ownership. + /// + [Key("claimKind")] public string ClaimKind { get; set; } = string.Empty; + /// + /// Gets or sets the content hash of the witness claim. + /// + [Key("claimHash")] public string ClaimHash { get; set; } = string.Empty; + /// + /// Gets or sets optional human-readable or app-specific claim detail. + /// + [Key("claimSummary")] public string? ClaimSummary { get; set; } + /// + /// Gets or sets the witness weight. Normal clients should use 1. + /// + [Key("weight")] public double Weight { get; set; } = 1d; + /// + /// Gets or sets the observation timestamp. + /// + [Key("observedAt")] public string ObservedAt { get; set; } = string.Empty; + + /// + /// Computes a stable claim hash from ordered claim parts. + /// + public static string ComputeClaimHash(params string[] parts) + { + if (parts == null) throw new ArgumentNullException(nameof(parts)); + var canonical = string.Join("\u001F", parts.Select(part => part ?? string.Empty)); + using var sha = SHA256.Create(); + var bytes = sha.ComputeHash(Encoding.UTF8.GetBytes(canonical)); + return string.Concat(bytes.Select(value => value.ToString("x2"))); + } + } + + /// + /// Controls deterministic witness aggregation. + /// + public sealed class CultNetSimulationConsensusOptions + { + /// + /// Gets or sets the minimum distinct witnesses required before a claim can be accepted. + /// + public int MinimumWitnesses { get; set; } = 1; + /// + /// Gets or sets the minimum weight required before a claim can be accepted. + /// + public double MinimumWeight { get; set; } = 1d; + /// + /// Gets or sets the fraction of observed weight required for quorum. + /// + public double QuorumRatio { get; set; } = 0.5d; + } + + /// + /// A deterministic consensus candidate derived from witness observations. + /// + public sealed class CultNetSimulationConsensusCandidate + { + /// + /// Creates a consensus candidate. + /// + public CultNetSimulationConsensusCandidate( + string shardId, + long shardEpoch, + long frame, + string subjectId, + string claimKind, + string claimHash, + string? claimSummary, + int witnessCount, + double supportWeight, + double totalWeight, + bool hasQuorum) + { + ShardId = shardId; + ShardEpoch = shardEpoch; + Frame = frame; + SubjectId = subjectId; + ClaimKind = claimKind; + ClaimHash = claimHash; + ClaimSummary = claimSummary; + WitnessCount = witnessCount; + SupportWeight = supportWeight; + TotalWeight = totalWeight; + HasQuorum = hasQuorum; + } + + /// + /// Gets the shard id. + /// + public string ShardId { get; } + /// + /// Gets the shard epoch. + /// + public long ShardEpoch { get; } + /// + /// Gets the simulation frame. + /// + public long Frame { get; } + /// + /// Gets the subject id. + /// + public string SubjectId { get; } + /// + /// Gets the claim kind. + /// + public string ClaimKind { get; } + /// + /// Gets the claim hash. + /// + public string ClaimHash { get; } + /// + /// Gets optional claim detail. + /// + public string? ClaimSummary { get; } + /// + /// Gets the distinct witness count supporting this candidate. + /// + public int WitnessCount { get; } + /// + /// Gets supporting witness weight. + /// + public double SupportWeight { get; } + /// + /// Gets total observed witness weight for the same subject/frame/kind. + /// + public double TotalWeight { get; } + /// + /// Gets whether the candidate crossed the configured quorum. + /// + public bool HasQuorum { get; } + /// + /// Gets support divided by total observed weight. + /// + public double Confidence => TotalWeight <= 0d ? 0d : SupportWeight / TotalWeight; + } + + /// + /// Aggregates simulation observations into deterministic consensus candidates. + /// + public sealed class CultNetSimulationConsensus + { + private readonly CultNetSimulationConsensusOptions _options; + + /// + /// Creates a consensus aggregator. + /// + public CultNetSimulationConsensus(CultNetSimulationConsensusOptions? options = null) + { + _options = options ?? new CultNetSimulationConsensusOptions(); + } + + /// + /// Returns the strongest candidate for each observed shard/frame/subject/claim kind. + /// + public IReadOnlyList BuildCandidates( + IEnumerable observations) + { + if (observations == null) throw new ArgumentNullException(nameof(observations)); + var clean = observations + .Where(IsValid) + .GroupBy(DeduplicationKey) + .Select(group => group + .OrderByDescending(observation => observation.Weight) + .ThenBy(observation => observation.WitnessRuntimeId, StringComparer.Ordinal) + .First()) + .ToArray(); + + return clean + .GroupBy(SubjectKey) + .Select(BuildCandidate) + .OrderBy(candidate => candidate.ShardId, StringComparer.Ordinal) + .ThenBy(candidate => candidate.ShardEpoch) + .ThenBy(candidate => candidate.Frame) + .ThenBy(candidate => candidate.SubjectId, StringComparer.Ordinal) + .ThenBy(candidate => candidate.ClaimKind, StringComparer.Ordinal) + .ToArray(); + } + + private CultNetSimulationConsensusCandidate BuildCandidate( + IGrouping subjectGroup) + { + var totalWeight = subjectGroup.Sum(WeightOf); + var bestClaim = subjectGroup + .GroupBy(observation => observation.ClaimHash, StringComparer.Ordinal) + .Select(group => new + { + ClaimHash = group.Key, + Observations = group.ToArray(), + Weight = group.Sum(WeightOf) + }) + .OrderByDescending(candidate => candidate.Weight) + .ThenBy(candidate => candidate.ClaimHash, StringComparer.Ordinal) + .First(); + var first = bestClaim.Observations + .OrderBy(observation => observation.WitnessRuntimeId, StringComparer.Ordinal) + .First(); + var witnessCount = bestClaim.Observations + .Select(observation => observation.WitnessRuntimeId) + .Distinct(StringComparer.Ordinal) + .Count(); + var hasQuorum = witnessCount >= _options.MinimumWitnesses && + bestClaim.Weight >= _options.MinimumWeight && + totalWeight > 0d && + bestClaim.Weight / totalWeight >= _options.QuorumRatio; + + return new CultNetSimulationConsensusCandidate( + first.ShardId, + first.ShardEpoch, + first.Frame, + first.SubjectId, + first.ClaimKind, + bestClaim.ClaimHash, + first.ClaimSummary, + witnessCount, + bestClaim.Weight, + totalWeight, + hasQuorum); + } + + private static bool IsValid(CultNetSimulationObservation observation) + { + return observation != null && + !string.IsNullOrWhiteSpace(observation.WitnessRuntimeId) && + !string.IsNullOrWhiteSpace(observation.ShardId) && + !string.IsNullOrWhiteSpace(observation.SubjectId) && + !string.IsNullOrWhiteSpace(observation.ClaimKind) && + !string.IsNullOrWhiteSpace(observation.ClaimHash) && + observation.Weight > 0d; + } + + private static double WeightOf(CultNetSimulationObservation observation) + { + return observation.Weight <= 0d ? 0d : observation.Weight; + } + + private static string DeduplicationKey(CultNetSimulationObservation observation) + { + return string.Join("|", + observation.WitnessRuntimeId, + observation.ShardId, + observation.ShardEpoch, + observation.Frame, + observation.SubjectId, + observation.ClaimKind); + } + + private static string SubjectKey(CultNetSimulationObservation observation) + { + return string.Join("|", + observation.ShardId, + observation.ShardEpoch, + observation.Frame, + observation.SubjectId, + observation.ClaimKind); + } + } +} diff --git a/src/GameCult.Networking/README.md b/src/GameCult.Networking/README.md index 97c2222e..f2f9ab34 100644 --- a/src/GameCult.Networking/README.md +++ b/src/GameCult.Networking/README.md @@ -154,6 +154,13 @@ local cache immediately and emits a `Predicted` change; when the authoritative shard log arrives for the same record, the database emits `Reconciled` and the cache holds the committed value. +For mesh-side simulation agreement, `CultNetSimulationObservation` records what +a witness saw for one shard epoch, frame, subject, and claim kind. +`CultNetSimulationConsensus` deterministically aggregates those observations +into candidates with support weight, total observed weight, confidence, and +quorum status. Those candidates are opinions ready for an authoritative commit +path, not committed world state by themselves. + The first coherent shard policy is primary ownership. Each shard has one authoritative writer at a time. Clients may connect to any node; a non-owner node forwards a write to the owner or rejects it honestly when forwarding is diff --git a/tests/GameCult.Networking.Tests/NetworkingTests.cs b/tests/GameCult.Networking.Tests/NetworkingTests.cs index fe09adff..c94439ae 100644 --- a/tests/GameCult.Networking.Tests/NetworkingTests.cs +++ b/tests/GameCult.Networking.Tests/NetworkingTests.cs @@ -1213,6 +1213,119 @@ namespace GameCult.Networking.Tests } } + [Test] + public void CultNetSimulationConsensus_Builds_QuorumCandidate_FromWitnesses() + { + var hitA = CultNetSimulationObservation.ComputeClaimHash("hit", "alice", "bob", "frame:100"); + var hitB = CultNetSimulationObservation.ComputeClaimHash("hit", "charlie", "bob", "frame:100"); + var consensus = new CultNetSimulationConsensus(new CultNetSimulationConsensusOptions + { + MinimumWitnesses = 2, + QuorumRatio = 0.6d + }); + + var candidates = consensus.BuildCandidates( + [ + new CultNetSimulationObservation + { + WitnessRuntimeId = "watcher-1", + ShardId = "arena", + ShardEpoch = 4, + Frame = 100, + SubjectId = "bob", + ClaimKind = "hit", + ClaimHash = hitA, + ClaimSummary = "alice hit bob first" + }, + new CultNetSimulationObservation + { + WitnessRuntimeId = "watcher-2", + ShardId = "arena", + ShardEpoch = 4, + Frame = 100, + SubjectId = "bob", + ClaimKind = "hit", + ClaimHash = hitA + }, + new CultNetSimulationObservation + { + WitnessRuntimeId = "watcher-3", + ShardId = "arena", + ShardEpoch = 4, + Frame = 100, + SubjectId = "bob", + ClaimKind = "hit", + ClaimHash = hitB, + ClaimSummary = "charlie hit bob first" + } + ]); + + Assert.That(candidates, Has.Count.EqualTo(1)); + Assert.That(candidates[0].ClaimHash, Is.EqualTo(hitA)); + Assert.That(candidates[0].WitnessCount, Is.EqualTo(2)); + Assert.That(candidates[0].SupportWeight, Is.EqualTo(2d)); + Assert.That(candidates[0].TotalWeight, Is.EqualTo(3d)); + Assert.That(candidates[0].HasQuorum, Is.True); + } + + [Test] + public void CultNetSimulationConsensus_DeduplicatesWitness_AndBreaksTiesDeterministically() + { + var lowerHash = CultNetSimulationObservation.ComputeClaimHash("a"); + var higherHash = CultNetSimulationObservation.ComputeClaimHash("b"); + if (string.CompareOrdinal(lowerHash, higherHash) > 0) + { + (lowerHash, higherHash) = (higherHash, lowerHash); + } + var consensus = new CultNetSimulationConsensus(new CultNetSimulationConsensusOptions + { + QuorumRatio = 0.5d + }); + + var candidates = consensus.BuildCandidates( + [ + new CultNetSimulationObservation + { + WitnessRuntimeId = "watcher-1", + ShardId = "arena", + ShardEpoch = 1, + Frame = 20, + SubjectId = "door", + ClaimKind = "state", + ClaimHash = higherHash, + Weight = 1d + }, + new CultNetSimulationObservation + { + WitnessRuntimeId = "watcher-1", + ShardId = "arena", + ShardEpoch = 1, + Frame = 20, + SubjectId = "door", + ClaimKind = "state", + ClaimHash = lowerHash, + Weight = 0.5d + }, + new CultNetSimulationObservation + { + WitnessRuntimeId = "watcher-2", + ShardId = "arena", + ShardEpoch = 1, + Frame = 20, + SubjectId = "door", + ClaimKind = "state", + ClaimHash = lowerHash, + Weight = 1d + } + ]); + + Assert.That(candidates, Has.Count.EqualTo(1)); + Assert.That(candidates[0].ClaimHash, Is.EqualTo(lowerHash)); + Assert.That(candidates[0].TotalWeight, Is.EqualTo(2d)); + Assert.That(candidates[0].SupportWeight, Is.EqualTo(1d)); + Assert.That(candidates[0].HasQuorum, Is.True); + } + [Test] public void CultNetDatabaseServer_Creates_Filtered_SubscriptionChange() {