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()
{